Open_Ultra_SAST/AGENTS.md

# Agentic SDLC and Spec-Driven Development

Kiro-style Spec-Driven Development on an agentic SDLC

## Project Memory
Project memory keeps persistent guidance (steering, specs notes, component docs) so OpenCode honors your standards each run. Treat it as the long-lived source of truth for patterns, conventions, and decisions.

- Use `.kiro/steering/` for project-wide policies: architecture principles, naming schemes, security constraints, tech stack decisions, api standards, etc.
- Use local `AGENTS.md` files for feature or library context (e.g. `src/lib/payments/AGENTS.md`): describe domain assumptions, API contracts, or testing conventions specific to that folder. OpenCode auto-loads these when working in the matching path.
- Specs notes stay with each spec (under `.kiro/specs/`) to guide specification-level workflows.

## Project Context

### Paths
- Steering: `.kiro/steering/`
- Specs: `.kiro/specs/`

### Steering vs Specification

**Steering** (`.kiro/steering/`) - Guide AI with project-wide rules and context
**Specs** (`.kiro/specs/`) - Formalize development process for individual features

### Active Specifications
- Check `.kiro/specs/` for active specifications
- Use `/kiro-spec-status [feature-name]` to check progress

## Development Guidelines
- Think in English, generate responses in English. All Markdown content written to project files (e.g., requirements.md, design.md, tasks.md, research.md, validation reports) MUST be written in the target language configured for this specification (see spec.json.language).

## Minimal Workflow
- Phase 0 (optional): `/kiro-steering` (bootstrap, sync, or a custom steering document)
- Discovery: `/kiro-discovery "idea"` — determines action path, writes brief.md + roadmap.md for multi-spec projects
- Phase 1 (Specification), one spec at a time, each phase human-reviewed:
  - `/kiro-spec-init "description"`
  - `/kiro-spec-requirements {feature}`
  - `/kiro-spec-design {feature} [-y | --gap | --review]` (`--gap`: optional gap analysis against the existing code first; `--review`: optional interactive review of an existing design; the design-review gate always runs)
  - `/kiro-spec-tasks {feature} [-y]`
  - Multi-spec projects: the specs of roadmap.md in dependency order, with the same steps each
- Phase 2 (Implementation): `/kiro-impl {feature} [tasks]`
  - Without task numbers: autonomous mode (subagent per task + independent review + final validation)
  - With task numbers: manual mode (selected tasks in main context, still reviewer-gated before completion)
  - `/kiro-validate-impl {feature}` (standalone re-validation)
- Progress check: `/kiro-spec-status {feature}` (use anytime)

## Skills Structure
Skills are located in `.agents/skills/*/SKILL.md` (the plural directory OpenCode searches by default; moved from `.opencode/skills` on 2026-10-02)
- Each skill is a directory with a `SKILL.md` file
- Use `/skills` to inspect currently available skills
- Invoke a skill directly with `/kiro-<skill-name>`
- **If there is even a 1% chance a skill applies to the current task, invoke it.** Do not skip skills because the task seems simple.
- Workflow skills: `kiro-steering`, `kiro-discovery`, `kiro-spec-init`, `kiro-spec-requirements`, `kiro-spec-design`, `kiro-spec-tasks`, `kiro-impl`, `kiro-validate-impl`, `kiro-spec-status`
- `kiro-review` — task-local adversarial review protocol used by reviewer subagents
- `kiro-debug` — root-cause-first debug protocol used by debugger subagents; carries the instrument rule below
- `kiro-verify-completion` — fresh-evidence gate before success or completion claims; carries the instrument rule below
- Product skills for users of the tool (the only ones user documentation names): `openultrasast-scan`, `openultrasast-triage`
- Reviewed 2026-10-02: `kiro-spec-quick`, `kiro-spec-batch` removed (no fast-track or parallel spec creation); `kiro-validate-gap` and `kiro-validate-design` merged into `kiro-spec-design` (`--gap`, `--review`); `kiro-steering-custom` merged into `kiro-steering`; `openultrasast-fix-audit` merged into `openultrasast-triage`

## Development Rules
- 3-phase approval workflow: Requirements → Design → Tasks → Implementation
- Human review required each phase; use `-y` only for intentional fast-track
- Keep steering current and verify alignment with `/kiro-spec-status`
- Follow the user's instructions precisely, and within that scope act autonomously: gather the necessary context and complete the requested work end-to-end in this run, asking questions only when essential information is missing or the instructions are critically ambiguous.

### Verify the instrument before you believe the measurement
Every wrong diagnosis this project has recorded came from the same shape: **the input was unreadable and the
tool reported a plausible zero.** `file_exists()` false, the parser writes nothing, the frontend exits 0 —
and "no errors, 0 findings" reads exactly like a clean result. It has cost four wrong root causes in one day
and two in an earlier session, twice from the same `php` shim.

So, before reporting any measurement:

1. **Prove the tool read its input.** Make it open one file and print the size. A zero from an unread tree
   and a zero from clean code are indistinguishable afterwards. `JoernBackend` now does this itself; a
   scratch harness must do it too.
2. **Distrust a number that is too good.** A joern script "finishing" in 0.5s when a JVM takes 15s to start
   is a failed launch. A harness must fail loudly with the exit code, never print `rows=?` next to a time.
3. **Prefer the shipped environment.** The Docker image has a native `php`; local wrappers that proxy stdio
   are not valid instruments for `php2cpg`, which depends on stream ordering.
4. **When a result contradicts a working baseline, suspect the instrument first.** Slices that found CVEs an
   hour ago do not stop working because a repository is larger.

## Steering Configuration
- Load entire `.kiro/steering/` as project memory
- Core files in this repository: `overview.md` (current state wins over dated history), `roadmap.md`, `safety-net.md`
- Custom files may exist beside them and carry equal weight (created via `/kiro-steering`, templates under `.kiro/settings/templates/steering-custom/`)