feature-loop

name	feature-loop
description	Coding agent for the project-level harness — one feature per session, must verify, must be mergeable.
requires_tools	["project_status","feature_select","feature_complete","verify_run","progress_append","code_outline","file_read","file_write","bash_exec"]

Feature Loop

Use when session_mode == feature_loop and the project is past the Initializer phase (system prompt will say "Coding 阶段").

Iron rules

1. One feature per session. Multiple in_progress features are forbidden by the store; do not bypass.
2. Always verify before commit. feature_complete rejects features that have not been promoted to verified via verify_run.
3. Keep the branch mergeable. Each commit must compile, pass verify.yaml, and not depend on uncommitted local state.

Loop

1. Sync from disk. Call project_status first thing every session — it reads feature_list.json / status.json / progress.md and reseeds your understanding from the single source of truth.
2. Pick a feature.
   • If status.active_feature_id is already set, resume that one (the prompt block will tell you).
   • Otherwise call feature_select with no arguments to auto-pick the highest-priority pending feature with satisfied dependencies, or pass feature_id when the user names one.
3. Implement using code_dev phases (Explore → Read → Author):
   • Explore with code_outline, grep, optional code_search.
   • Read with file_read slices (start/end line). Track files you have read in scratchpad.
   • Author with file_write skeletons first, then section-by-section appends.
4. Run the gate. Call verify_run feature_id=<id>. If any step fails:
   • Do not call feature_complete.
   • Log a progress_append with the failing step name and root cause.
   • Decide: fix and rerun verify_run, or escalate to the user with the specific failure.
5. Commit via shell.

   git add -A
   git commit -m "feat(<feature_id>): <one-line summary>"
   

   Capture the resulting sha (git rev-parse HEAD).
6. Promote to committed. Call feature_complete feature_id=<id> commit_sha=<sha>. The store writes an immutable archive snapshot under .agx/project/archive/feature_<id>.json.
7. Decide next step. Either call feature_select for the next feature in the same session, or stop and tell the user the loop closed cleanly.

Failure modes

• verify_run timeouts: do not retry blindly. Inspect the log under .agx/project/archive/, fix the root cause, then rerun.
• Dependency missed: feature_select will reject features whose depends_on isn't committed. Either pick a different feature or finish the prerequisite first.
• Lost context after window compaction: re-call project_status. Disk is the source of truth.
• Cold start (new machine, fresh session): project_status + feature_select is enough to resume. No memory of previous turns is required.

Forbidden

• Editing files inside .agx/project/archive/ (immutable).
• Calling project_init outside the Initializer phase.
• Skipping verify_run because "tests are too slow".