Implementation workflow

Works with or without

aoc

Build/Test Commands (from constitution)

Implementation uses project-specific commands from constitution.md:

# Read actual commands from .agent/constitution.md
build: uv run python -m build     # or: npm run build
lint: uv run ruff check .         # or: npm run lint  
test: uv run pytest               # or: npm run test
format: uv run ruff format .      # or: npm run format

Issue Tracking (File-Based — Default)

.agent/issues/{priority}.md

status: in_progress

### Log

- YYYY-MM-DD: Completed step 1

status: done

history.md

Example Implementation Flow (File-Based)

1. Edit issue in

   .agent/issues/{priority}.md

   — set

   status: in_progress

2. Update

   .agent/focus.md

   — "Implementing {ISSUE-ID}"
3. Run tests after each change (from constitution)
4. Edit issue — add log entry for progress
5. When done, set

   status: done

   , add final log entry, move to

   history.md

CLI Integration (when aoc is available)

When

aoc

.agent/tools.json

aoc issues update <ID> --status in-progress

aoc issues update <ID> --log "Completed step 1"

aoc issues create --type CHORE --title "..."

aoc issues close <ID> --log "Done"

Preconditions

• Constitution is confirmed.
• Baseline exists.
• Final plan exists and is approved (or stop and ask for approval).
• Work is tracked as an issue (or create one before starting).
• Implementation details file exists (from planning phase) — check

  .agent/issues/references/{ISSUE-ID}-impl-plan.md

Using Implementation Details

Before starting implementation, check for implementation details:

1. Look for

   .agent/issues/references/{ISSUE-ID}-impl-plan.md

2. If exists, use it as the primary implementation guide:
   • Follow the detailed code snippets (extensive level)
   • Reference function signatures (normal level)
   • Use file list and approach (low level)
3. If not exists, proceed with plan only (but consider generating details first)

During implementation, reference the details file for:

• Exact function signatures to implement
• Edge cases to handle
• Error scenarios to cover
• Test cases to write

Issue Tracking During Implementation

1. Reference the issue being worked on:

   • Update issue status to

     in_progress

   • Note in focus.md: "Implementing {ISSUE-ID}"

2. Track deferred work:

   • If you notice something that needs fixing but is out of scope:
   • Create a new issue, don't fix it now
   • Add to current issue's notes: "Related: {NEW-ISSUE-ID}"

Procedure

1. Implement in small steps (reviewable diffs).
2. After each step:
   • run the smallest reliable test subset
   • update focus
3. Log file creations (see File Audit Trail below)
4. If ambiguity appears:
   • stop and ask; do not guess
5. Avoid refactors:
   • if a refactor seems necessary, create an issue + ask permission before doing it.
6. End-of-implementation:
   • run full test suite (or constitution-defined test command)
   • prepare for critical review skill.

File Audit Trail

When creating files OUTSIDE

.agent/

This enables

agent-ops-selective-copy

What to Log

• Files created in

  src/

  ,

  tests/

  ,

  docs/

  , etc.
• Configuration files added to project root
• Any file the user didn't explicitly create themselves

What NOT to Log

• Files inside

  .agent/

  (already excluded by convention)
• Files inside

  .github/skills/

  ,

  .github/prompts/

  ,

  .github/agents/

  (already excluded)
• Temporary files that will be deleted

Log Format

Append to

.agent/log/created-files.log

{ISO-timestamp} {action} {relative-path}

Actions:

CREATE

MODIFY

DELETE

Logging Commands

PowerShell:

$timestamp = (Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ")
Add-Content -Path ".agent/log/created-files.log" -Value "$timestamp CREATE src/new-file.py"

Bash:

echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) CREATE src/new-file.py" >> .agent/log/created-files.log

Example Flow

When implementing a feature that creates

src/utils/helper.py

1. Create the file
2. Log it:

   2026-01-20T10:15:32Z CREATE src/utils/helper.py

3. Continue with tests

Handling Unexpected Failures

If tests fail unexpectedly during implementation, invoke

agent-ops-debugging

1. Don't guess — use systematic debugging process
2. Isolate — is this from your changes or pre-existing?
3. Diagnose — form hypothesis, test it
4. Decide:
   • If your change caused it → fix before continuing
   • If pre-existing → document, create issue, continue
   • If unclear → escalate to user

⚠️ Test failure during implementation step {N}.

Debugging analysis:
- Hypothesis: {what you think caused it}
- Evidence: {what you found}

Options:
1. Fix and continue (my change caused this)
2. Create issue and continue (pre-existing)
3. Need help investigating

Issue Discovery After Implementation

After implementation complete, invoke

agent-ops-tasks

1. Collect follow-up items discovered during implementation:

   • TODOs left in code →

     CHORE

     issues
   • Edge cases to handle later →

     BUG

     or

     ENH

     issues
   • Tests to add →

     TEST

     issues
   • Documentation needed →

     DOCS

     issues
   • Related improvements noticed →

     ENH

     or

     REFAC

     issues

2. Present to user:

   📋 Implementation complete for {ISSUE-ID}. Found {N} follow-up items:
   
   - [TEST] Add edge case tests for empty input
   - [DOCS] Document new API endpoint
   - [ENH] Consider caching for performance
   
   Create issues for these? [A]ll / [S]elect / [N]one
   

3. Update original issue:

   • Status:

     done

     (or

     blocked

     if follow-ups are required)
   • Log: "YYYY-MM-DD: Implementation complete, {N} follow-up issues created"

4. After creating issues:

   Created {N} follow-up issues. What's next?
   
   1. Run critical review on changes
   2. Start next priority issue
   3. Work on follow-up item ({ISSUE-ID})
   4. Mark original issue done and commit
   

Low Confidence Hard Stop (MANDATORY)

When confidence is LOW, implementation MUST stop after EACH issue for human review.

This is non-negotiable. Low confidence means high uncertainty — human oversight is critical.

Hard Stop Trigger

After completing implementation of a LOW confidence issue:

1. DO NOT proceed to next issue automatically
2. DO NOT batch multiple issues
3. MUST present hard stop checkpoint

Hard Stop Checkpoint Template

🛑 LOW CONFIDENCE HARD STOP — Human Review Required

## Implementation Complete: {ISSUE-ID}

### Changes Made
- {file1}: {description of change}
- {file2}: {description of change}

### Tests Executed
- Test command: {command from constitution}
- Result: {PASS/FAIL} ({N} tests, {coverage}% coverage)
- New tests added: {count}

### Coverage Analysis
- Lines changed: {N}
- Lines covered by tests: {N} ({percentage}%)
- Branches covered: {N} ({percentage}%)

### Implementation Details Reference
- Spec file: {path to impl-plan.md}
- Adherence: {followed spec / deviated because...}

### Questions for Reviewer
1. {Any uncertainties encountered}
2. {Any assumptions made}

---

⏸️ WAITING FOR HUMAN APPROVAL

Please review the changes and respond:
- [A]pprove — continue to next issue or critical review
- [R]equest changes — specify what needs modification
- [D]iscuss — need clarification before deciding

After Human Approval

Only after explicit human approval:

1. Update issue status to

   done

   (or

   needs-changes

   if requested)
2. Log the approval in issue notes
3. Proceed to critical review OR next issue (human's choice)

Batch Size Enforcement

For LOW confidence, batch size is ALWAYS 1. The agent must not group issues.