piv-system-evolution

An Archon workflow that runs the PIV loop (Plan → Implement → Validate) on a feature or bug — and then closes the loop by evolving the codebase's own AI Layer based on what the run learned.

A normal coding loop ends with a PR. This one ends with a PR and a better AI Layer: the CLAUDE.md, command prompts, and references the next agent will rely on.

What it does

Thirteen nodes. Eight of them are the agentic-coding-course AI Layer — prime, plan, implement, validate, code-review, code-review-fix, execution-report, system-review — adapted into Archon command files. The other five are workflow-native: four human gates and a finalize node. The workflow is the wiring; the AI Layer commands are the engine.

prime → [GATE: prime-review] → plan → [GATE: plan-review]
      → implement → validate → code-review → code-review-fix
      → [GATE: implementation-review] → execution-report → system-review
      → [GATE: system-evolution] → finalize (draft PR)

Four human-in-the-loop gates

1. prime-review — after the agent has read the issue and the codebase, you confirm or correct its understanding before any planning happens.
2. plan-review — you review and edit the implementation plan before any code is written.
3. implementation-review — after the code is built, validated, and the automated code review's findings are fixed, you review the change set line-by-line in the git diff and do your own manual testing. Bugs or change requests you raise are applied before the run continues.
4. system-evolution — the headline. The system-review command proposes concrete updates to the AI Layer (CLAUDE.md, command prompts, new commands). You curate that list — accept, edit, reject — and the approved changes are committed alongside the fix.

Between the gates the autonomous commands run unattended: implement → validate → code-review → code-review-fix between gates 2 and 3, and execution-report → system-review between gates 3 and 4.

Install

From inside any git repository:

archon workflow install piv-system-evolution

This drops piv-system-evolution.yaml into .archon/workflows/ and the eight piv-* command files into .archon/commands/.

Run

archon workflow run piv-system-evolution --branch fix/issue-123 "Fix issue #123"

Input can be a GitHub issue number, a feature description, or a path to an existing plan. The workflow runs in an isolated worktree and ends in a draft PR — review the PR to validate the result.

Requirements

• Archon CLI (archonVersionCompat: >=0.3.0)
• git and the GitHub CLI (gh) authenticated
• The target repo's own test/lint/type-check tooling — validate auto-detects it

License

MIT — see LICENSE.