AI-Native SDLC

AI-Native SDLC — The Artifact Chain

MANDATORY FOR ALL AI AGENTS: Every stage of work commits one artifact that the next stage reads. You MUST NOT start a stage whose input artifact does not exist and is not approved. The chain of commits — author, timestamp, SHA — IS the audit trail; there is no second system of record to reconcile it against. An agent may act up to a gate and MUST NOT pass one.

The bottleneck is no longer writing code. It is the human-speed steps around it: getting an idea into a reviewable shape, turning requirements into a plan, waiting for a first review, noticing a regression. This file is the spine that says which artifact each stage owes, who approves it, and what gets measured.

Companion files: evals.md (Test stage gate), hooks.md (where controls live), gsd-guide.md (the command surface that executes stages 1–5), adr.md (decisions that outlive a phase), observability.md (the signal the Maintain loop watches).

1. The chain

1
intent.md ──▶ spec.md ──▶ plan.md ──▶ diff + tests ──▶ PR + review ──▶ production
2
    ▲                                                                      │
3
    └──────────────── band breach / scan finding / incident ◀──────────────┘

Each arrow is a trigger, not a handoff meeting. Each box is a commit.

Why commits and not a tracker: the chain is already immutable, attributed and timestamped. A separate tool means reconciling two records, and the one nobody updates becomes the one the auditor reads.

When a legacy system is authoritative for an artifact — a compliance tool of record — designate it as the source of truth for that one artifact and link to it from the commit. Do not maintain both.

2. Stages, mapped to what exists here

Where each control belongs

Putting any row in the wrong stage is the single most common structural mistake: an approval prompt during Build (stalls everything), or a convention left to review (found weeks late, by a person, repeatedly).

3. Institutional knowledge

CLAUDE.md — one page

Build/test/lint commands, conventions, architecture pointers, the mistakes made twice. Not research dumps, version comparison tables, or link lists.

This is currently violated. The ForgeOS CLAUDE.md carries the full technology-stack research — version matrices, sources, alternatives considered, what-not-to-use. That is an ADR and a docs/context/ document; every turn of every session pays for it in tokens and in dilution of the instructions that actually change behaviour. Move it out, leave pointers.

The maintenance rule is mechanical: the agent makes the same mistake twice → the correction goes in CLAUDE.md, and something of equal length comes out. A file that only grows stops being read carefully, by humans and models alike.

Skills — policy, versioned centrally

A skill is a policy with a trigger. Its frontmatter decides whether it fires at all, which makes the description the most load-bearing line in the file — and the one most likely to silently regress. That is precisely what evals.md cases with "bare": false defend.

Fifty-plus skills is past the point where the index in CLAUDE.md can be trusted by inspection. Trust it by test.

4. Metrics

Measure the process, not only the code. Coverage at 80% says nothing about whether the loop is working.

The substrate already exists: ~/.claude/metrics/usage.jsonl and gsd-context-monitor.js collect per-tool telemetry today, unused for any of the above. Deriving even two rows from it beats deriving none perfectly.

Read leading indicators weekly and lagging ones monthly. A leading indicator checked monthly is a lagging indicator.

5. Closing the loop — the missing stage

Everything upstream of production is covered here. Nothing downstream is: a metric degrades, and it re-enters the pipeline only when a human notices and files it by hand.

The loop closes with deterministic detection and a tiered agent response.

1
# bands.yaml — version-controlled, reviewed like code
2
metric: ci_failure_rate
3
window: 14d
4
tiers:
5
  - sigma: 1        # noise
6
    action: log
7
  - sigma: 2        # something moved
8
    action: diagnose      # read-only agent, no write access
9
  - sigma: 3        # act
10
    action: propose       # agent opens a PR, or runs a pre-approved runbook

Detection is a script, not a model. Mean and standard deviation over a window, Western Electric rules or equivalent. An agent asked “is this bad?” gives a different answer on Tuesday; a control chart does not. The agent’s job starts after the breach is established: diagnose, evidence, proposal.

Response at tier 3 is an intent.md in a triage queue — anomaly, evidence, proposed outcome, affected systems, open questions. It re-enters at Stage 1 and takes the same approval path as any other idea. Dismissals tune the bands. When the fix ships, the incident becomes a permanent eval case (evals.md §5).

Start with one metric that is already stable and already collected. CI failure rate is the usual first pick; post-deploy 5xx and PR cycle time follow.

For ForgeOS this is not just process hygiene — it is the product’s own thesis, dogfooded. Story → Spec → Agent → PR is exactly what tier 3 emits.

6. Parallelism

One task per session, one worktree per session (superpowers:using-git-worktrees, git-workflow.md). Split from PLAN.md, choosing tasks that touch disjoint files. Start at two or three concurrent sessions and raise the number only while review quality holds — throughput that outruns review is not throughput, it is queue.

Known hazard on this machine: parallel GSD orchestrators on one checkout collide on .planning/STATE.md and ROADMAP.md, and race .git/config.lock, even when the source files are disjoint. The planning ledger is shared state that the worktree split does not isolate. Check for status: executing before dispatching another execute-phase.

7. Roadmap

Dependency-ordered. Each item is cheap only because the one above it is done.

8. REVIEW.md — the review policy

Agent reviewers today run on implicit criteria, which makes their findings unarguable and untunable. Write the policy down, in the repo:

• Passes: Bugs and logic. Security, injection, PII. Compliance — does the diff match spec.md and plan.md.
• Important vs Nit: defined explicitly, with a cap of five nits per review. An uncapped reviewer produces a wall that gets skimmed, and the one real finding dies in it.
• Exclusions: generated code, vendored paths, formatting owned by Spotless.
• Threshold: findings neither approve nor block. Branch protection plus a human code owner does. The agent that wrote the code has no route to approving it.
• Tuning: monthly. Rate the findings, cut the classes that were never actionable.
• Feedback: a review finding raised twice becomes a CLAUDE.md line or an eval case — not a third finding.

9. Anti-patterns