zagrosi-implement

name	zagrosi-implement
description	Implement Zagrosi Forge section files with test-first development, focused review, documentation updates, and git hygiene. Use when the user has a sections directory from Zagrosi Plan and wants Codex to build the planned work incrementally with TDD and code review.

Zagrosi Implement

Implement $zagrosi-forge:zagrosi-plan section files one at a time. The workflow prioritizes small tested changes, review before commit, and resumable progress.

First Actions

1. Require a sections/ directory containing index.md.
2. Treat the Forge planning record as mandatory implementation input. Do not start from setup stubs, partial sections, missing reviews, or placeholder governance files. implement-setup enforces this with lint-plan-artifacts even when flight mode is off.
3. Resolve plugin_root as the nearest parent containing scripts/zagrosi_skills.py.
4. Determine target_dir, the repo where code should be written. Use the current working directory unless the user specifies another path or a previous config exists.
5. Run setup:

python3 {plugin_root}/scripts/zagrosi_skills.py implement-setup --sections-dir "{sections_dir}" --target-dir "{target_dir}"

This emits a preflight report automatically. Treat protected-branch and dirty working-tree warnings like Pierce-style preflight warnings: pause for user approval before editing when they affect the target repository. When showing the command for a human to run outside Codex, add --pretty.

6. Parse the JSON. If success is false, show the error and stop. If gate is plan-artifacts, resume $zagrosi-forge:zagrosi-plan; never patch code or record implementation against an incomplete planning dir.
7. If setup warns about a protected branch or dirty working tree, ask whether to continue before editing.
8. Run section readiness gates:

python3 {plugin_root}/scripts/zagrosi_skills.py lint-plan-artifacts --planning-dir "{planning_dir}" --strict
python3 {plugin_root}/scripts/zagrosi_skills.py lint-sections --planning-dir "{planning_dir}"
python3 {plugin_root}/scripts/zagrosi_skills.py traceability --planning-dir "{planning_dir}"
python3 {plugin_root}/scripts/zagrosi_skills.py lint-implementation-readiness --planning-dir "{planning_dir}"
python3 {plugin_root}/scripts/zagrosi_skills.py next-section --planning-dir "{planning_dir}"

9. Use update_plan when available with one milestone group per section: implement, review, fix, document, record. Add commit milestones only when using section commits.

Section Loop

For each incomplete section in SECTION_MANIFEST order:

1. Read

Read the section file and sections/index.md. If the section depends on earlier sections, verify those are recorded complete or already present in the codebase.

For large plans, generate a focused packet before implementation:

python3 {plugin_root}/scripts/zagrosi_skills.py implementation-packet --planning-dir "{planning_dir}" --section "{section}"
python3 {plugin_root}/scripts/zagrosi_skills.py context-brief --planning-dir "{planning_dir}" --section "{section}"

If the next section is too broad or owns too many files, ask Forge for a split proposal before writing tests:

python3 {plugin_root}/scripts/zagrosi_skills.py suggest-section-splits --planning-dir "{planning_dir}"

2. Test First

Follow references/tdd-review-git.md.

Create or update tests before implementation. Run the targeted test command and confirm the expected failure. If the failure is not meaningful, fix the test before writing production code.

If helpful, generate throwaway red-test skeletons from the TDD plan:

python3 {plugin_root}/scripts/zagrosi_skills.py tdd-skeletons --planning-dir "{planning_dir}" --framework pytest

3. Implement

Make the smallest coherent implementation for the section. Follow existing repo patterns. Do not refactor unrelated code.

Run targeted tests, then the section's configured test_command when practical. Iterate until tests pass or a real blocker is clear.

Record milestones for long sections:

python3 {plugin_root}/scripts/zagrosi_skills.py implement-progress --planning-dir "{planning_dir}" --section "{section}" --stage red --result "targeted test failed as expected"

4. Stage and Review

If this is a git repo, stage only files related to the section. Save the diff to:

{planning_dir}/implementation/code_review/{section}-diff.md

Validate staged or saved scope against the section:

python3 {plugin_root}/scripts/zagrosi_skills.py patch-scope --section-file "{section_file}" --repo "{target_dir}" --staged
python3 {plugin_root}/scripts/zagrosi_skills.py implementation-drift --planning-dir "{planning_dir}" --repo "{target_dir}" --staged --strict

Run an adversarial review. If subagents are explicitly authorized, delegate a bounded review task with the section file and diff path; otherwise perform the review locally.

Write:

{planning_dir}/implementation/code_review/{section}-review.md

Every implemented section needs a review record. If external review tooling is configured and the user opted in, include it as additional evidence; otherwise the local Codex review is the mandatory fallback.

5. Triage Review

Fix correctness, security, data loss, and requirement-mismatch issues before continuing. Ask the user only about product choices, tradeoffs, or changes that alter scope.

Review decisions are required, even when the review has no blocking findings. Record decisions in:

{planning_dir}/implementation/code_review/{section}-decisions.md

6. Update Section Documentation

Before committing, update the section file so it reflects what was actually built. Use references/section-update.md.

7. Commit Strategy

If in a git repo, choose the commit strategy from user or repo preference:

• Section commits: commit each section's implementation, tests, review artifacts that live inside the repo, and section doc updates that live inside the repo.
• Consolidated commit: do not create small record commits after each section. Record section completion with --commit none or the pending final commit label, then make one normal feature commit after final verification. If the planning directory is ignored, do not force-add local planning artifacts.

Use the repo's commit style. Never bypass hooks unless the user explicitly instructs it after seeing the failure.

If the repo has no clear commit style, generate a section-based draft:

python3 {plugin_root}/scripts/zagrosi_skills.py commit-message --section-file "{section_file}"

8. Record

Record completion:

python3 {plugin_root}/scripts/zagrosi_skills.py implement-record-section \
  --sections-dir "{sections_dir}" \
  --section "{section}" \
  --commit "{commit_hash_or_none}" \
  --notes "{short_note}" \
  --file "{changed_file}" \
  --test-file "{test_file}" \
  --review-artifact "implementation/code_review/{section}-review.md" \
  --review-artifact "implementation/code_review/{section}-decisions.md" \
  --verification "{test_or_gate_command}"

This updates implementation state and refreshes {planning_dir}/traceability.md so requirement status follows recorded section completion. After a squash, amend, rebase, or final consolidated commit, refresh each section record with the final commit hash and the same file, test, review, and verification evidence so traceability does not point at stale history.

Then continue to the next section.

Completion

After all sections are recorded complete:

1. Run the full configured test_command.
2. Write {planning_dir}/implementation/usage.md with practical usage notes.
3. If using a consolidated commit, stage the completed implementation once and commit it in the repo's normal style.
4. Run final gates:

python3 {plugin_root}/scripts/zagrosi_skills.py lint-implementation-state --sections-dir "{sections_dir}"
python3 {plugin_root}/scripts/zagrosi_skills.py postflight --phase implement --planning-dir "{planning_dir}" --sections-dir "{sections_dir}" --target-dir "{target_dir}" --staged
python3 {plugin_root}/scripts/zagrosi_skills.py status --path "{planning_dir}"
python3 {plugin_root}/scripts/zagrosi_skills.py report --planning-dir "{planning_dir}"

5. Summarize completed sections, commits, review files, tests run, and any residual risks.

Do not push, open a PR, start a CI watch, or run a fix-watch loop unless the user asks or has explicitly opted into that autonomy mode.