agent-implementation-skill

Category: Tools & Productivity | Uploader: nestharus | Downloads: 0 | Version: v1.0（Latest）

Multi-model agent implementation workflow for software development. Orchestrates research, evaluation, design baseline, implementation, RCA, structured decomposition, constraint discovery, model selection, and agent-driven Stage 3 codemap exploration across external AI models (GPT, GLM, Claude). Use when implementing features through a structured multi-phase pipeline with planspace/codespace separation, dynamic scheduling, and SQLite-backed agent coordination.

Changelog: Source: GitHub https://github.com/nestharus/agent-implementation-skill

Directory Structure

Current level: src/

📁 coordination/
- 📁 agents/
  - 📄 bridge-agent.md 2.1 KB
  - 📄 consequence-note-triager.md 2.6 KB
  - 📄 coordination-fixer.md 5.0 KB
  - 📄 coordination-planner.md 4.1 KB
  - 📄 recurrence-adjudicator.md 2.3 KB
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 coordination_controller.py 8.5 KB
  - 📄 global_coordinator.py 17.7 KB
  - 📄 plan_executor.py 16.6 KB
- 📁 prompt/
  - 📄 __init__.py 0 B
  - 📄 writers.py 8.7 KB
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 notes.py 1.4 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 completion_handler.py 9.2 KB
  - 📄 decision_recorder.py 546 B
  - 📄 planner.py 8.0 KB
  - 📄 problem_resolver.py 10.8 KB
  - 📄 stall_detector.py 2.8 KB
- 📄 __init__.py 317 B
- 📄 routes.py 678 B
📁 dispatch/
- 📁 agents/
  - 📄 agent-monitor.md 2.9 KB
  - 📄 bridge-tools.md 2.5 KB
  - 📄 tool-registrar.md 4.3 KB
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 agent_executor.py 1.7 KB
  - 📄 section_dispatcher.py 7.4 KB
- 📁 helpers/
  - 📄 __init__.py 0 B
  - 📄 log_extract_helpers.py 2.1 KB
  - 📄 signal_checker.py 2.0 KB
- 📁 prompt/
  - 📄 __init__.py 0 B
  - 📄 context_assembler.py 5.5 KB
  - 📄 context_builder.py 10.0 KB
  - 📄 prompt_formatters.py 1.7 KB
  - 📄 writers.py 19.6 KB
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 metadata.py 1.2 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 context_sidecar.py 7.0 KB
  - 📄 model_policy.py 5.7 KB
  - 📄 monitor_service.py 3.7 KB
  - 📄 output_adjudicator.py 3.0 KB
  - 📄 prompt_guard.py 2.9 KB
  - 📄 tool_registry_manager.py 20.6 KB
- 📄 __init__.py 419 B
- 📄 routes.py 355 B
📁 flow/
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 flow_submitter.py 6.4 KB
  - 📄 reconciler.py 14.3 KB
  - 📄 task_dispatcher.py 15.0 KB
- 📁 helpers/
  - 📄 __init__.py 0 B
  - 📄 task_parser.py 569 B
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 catalog.py 6.9 KB
  - 📄 flow_context_store.py 4.8 KB
  - 📄 gate_repository.py 7.7 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 flow_facade.py 645 B
  - 📄 flow_signal_parser.py 3.6 KB
  - 📄 notifier.py 2.7 KB
  - 📄 task_db_client.py 1.3 KB
  - 📄 task_request_ingestor.py 5.5 KB
- 📁 types/
  - 📄 __init__.py 0 B
  - 📄 context.py 2.7 KB
  - 📄 routing.py 2.4 KB
  - 📄 schema.py 13.0 KB
- 📄 __init__.py 207 B
- 📄 exceptions.py 173 B
📁 implementation/
- 📁 agents/
  - 📄 implementation-strategist.md 8.8 KB
  - 📄 microstrategy-decider.md 2.2 KB
  - 📄 microstrategy-writer.md 5.5 KB
  - 📄 post-implementation-assessor.md 1.5 KB
  - 📄 section-re-explorer.md 3.5 KB
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 implementation_cycle.py 16.6 KB
  - 📄 implementation_phase.py 19.4 KB
  - 📄 section_pipeline.py 17.9 KB
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 roal_index.py 3.6 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 change_verifier.py 1.9 KB
  - 📄 file_snapshotter.py 2.5 KB
  - 📄 impact_analyzer.py 12.9 KB
  - 📄 microstrategy_decider.py 8.4 KB
  - 📄 microstrategy_generator.py 7.4 KB
  - 📄 risk_artifact_writer.py 7.8 KB
  - 📄 risk_history_recorder.py 6.8 KB
  - 📄 scope_delta_aggregator.py 11.0 KB
  - 📄 scope_delta_parser.py 2.6 KB
  - 📄 section_reexplorer.py 8.3 KB
  - 📄 trace_map_builder.py 3.1 KB
  - 📄 traceability_writer.py 9.3 KB
  - 📄 triage_orchestrator.py 5.7 KB
- 📄 __init__.py 345 B
- 📄 routes.py 743 B
📁 intake/
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 governance_loader.py 17.1 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 assessment_evaluator.py 9.3 KB
  - 📄 governance_packet_builder.py 11.7 KB
- 📄 __init__.py 332 B
📁 intent/
- 📁 agents/
  - 📄 intent-judge.md 5.7 KB
  - 📄 intent-pack-generator.md 4.7 KB
  - 📄 intent-triager.md 4.9 KB
  - 📄 philosophy-bootstrap-prompter.md 2.1 KB
  - 📄 philosophy-distiller.md 6.3 KB
  - 📄 philosophy-expander.md 5.5 KB
  - 📄 philosophy-source-selector.md 4.0 KB
  - 📄 philosophy-source-verifier.md 3.4 KB
  - 📄 problem-expander.md 4.0 KB
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 expansion_orchestrator.py 10.9 KB
  - 📄 intent_initializer.py 8.6 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 expanders.py 10.1 KB
  - 📄 expansion_facade.py 2.0 KB
  - 📄 intent_pack_generator.py 9.3 KB
  - 📄 intent_triager.py 10.0 KB
  - 📄 philosophy_bootstrapper.py 58.3 KB
  - 📄 philosophy_catalog.py 3.9 KB
  - 📄 philosophy_classifier.py 10.5 KB
  - 📄 philosophy_dispatcher.py 3.0 KB
  - 📄 recurrence_emitter.py 832 B
  - 📄 surface_registry.py 9.1 KB
- 📄 __init__.py 387 B
- 📄 routes.py 1.5 KB
📁 orchestrator/
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 pipeline_orchestrator.py 8.5 KB
  - 📄 strategic_state_builder.py 7.3 KB
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 decisions.py 5.4 KB
  - 📄 section_artifacts.py 940 B
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 pipeline_control.py 5.2 KB
  - 📄 pipeline_state.py 3.0 KB
  - 📄 section_decision_store.py 2.4 KB
- 📄 __init__.py 429 B
- 📄 path_registry.py 22.2 KB
- 📄 types.py 1.2 KB
📁 pipeline/
- 📄 __init__.py 624 B
- 📄 context.py 1.4 KB
- 📄 engine.py 3.2 KB
- 📄 middleware.py 2.3 KB
- 📄 template.py 3.8 KB
📁 proposal/
- 📁 agents/
  - 📄 integration-proposer.md 12.6 KB
  - 📄 setup-excerpter.md 1.5 KB
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 proposal_cycle.py 25.0 KB
  - 📄 proposal_phase.py 15.1 KB
  - 📄 readiness_gate.py 14.0 KB
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 excerpts.py 1.7 KB
  - 📄 state.py 4.5 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 excerpt_extractor.py 4.7 KB
  - 📄 expansion_handler.py 4.9 KB
  - 📄 problem_frame_gate.py 6.0 KB
  - 📄 readiness_resolver.py 9.7 KB
- 📄 __init__.py 417 B
- 📄 routes.py 351 B
📁 qa/
- 📁 agents/
  - 📄 qa-interceptor.md 3.8 KB
- 📁 helpers/
  - 📄 __init__.py 0 B
  - 📄 qa_verdict.py 1.4 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 qa_interceptor.py 11.5 KB
- 📄 __init__.py 0 B
- 📄 qa-harness.sh 15.5 KB
- 📄 routes.py 225 B
📁 reconciliation/
- 📁 agents/
  - 📄 reconciliation-adjudicator.md 2.7 KB
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 cross_section_reconciler.py 11.2 KB
  - 📄 reconciliation_phase.py 6.5 KB
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 queue.py 2.1 KB
  - 📄 results.py 3.0 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 adjudicator.py 3.3 KB
  - 📄 detectors.py 6.1 KB
- 📄 __init__.py 297 B
- 📄 routes.py 226 B
📁 research/
- 📁 agents/
  - 📄 domain-researcher.md 2.3 KB
  - 📄 research-planner.md 2.7 KB
  - 📄 research-synthesizer.md 3.0 KB
  - 📄 research-verifier.md 1.9 KB
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 orchestrator.py 3.2 KB
  - 📄 research_plan_executor.py 15.9 KB
- 📁 prompt/
  - 📄 __init__.py 0 B
  - 📄 writers.py 8.9 KB
- 📄 __init__.py 153 B
- 📄 routes.py 608 B
📁 risk/
- 📁 agents/
  - 📄 execution-optimizer.md 10.6 KB
  - 📄 risk-assessor.md 10.7 KB
  - 📄 stack-evaluator.md 2.1 KB
- 📁 engine/
  - 📄 __init__.py 0 B
  - 📄 risk_assessor.py 14.9 KB
- 📁 prompt/
  - 📄 __init__.py 0 B
  - 📄 writers.py 7.0 KB
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 history.py 4.3 KB
  - 📄 serialization.py 9.0 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 engagement.py 1.5 KB
  - 📄 fallback.py 1.9 KB
  - 📄 package_builder.py 14.5 KB
  - 📄 posture.py 3.8 KB
  - 📄 posture_hysteresis.py 5.1 KB
  - 📄 quantifier.py 11.2 KB
  - 📄 response_parser.py 1.8 KB
  - 📄 threshold.py 10.4 KB
- 📄 __init__.py 482 B
- 📄 routes.py 468 B
- 📄 types.py 5.4 KB
📁 scan/
- 📁 agents/
  - 📄 scan-codemap-builder.md 2.9 KB
  - 📄 scan-codemap-freshness-judge.md 2.5 KB
  - 📄 scan-codemap-verifier.md 2.2 KB
  - 📄 scan-file-analyzer.md 3.0 KB
  - 📄 scan-related-files-adjudicator.md 3.2 KB
  - 📄 scan-related-files-explorer.md 2.8 KB
  - 📄 scan-tier-ranker.md 2.6 KB
  - 📄 substrate-pruner.md 4.1 KB
  - 📄 substrate-seeder.md 3.2 KB
  - 📄 substrate-shard-explorer.md 3.4 KB
- 📁 codemap/
  - 📄 __init__.py 0 B
  - 📄 cache.py 4.7 KB
  - 📄 codemap_builder.py 10.1 KB
  - 📄 fingerprint.py 2.0 KB
- 📁 explore/
  - 📄 __init__.py 0 B
  - 📄 analyzer.py 5.2 KB
  - 📄 deep_scanner.py 3.5 KB
  - 📄 section_explorer.py 5.0 KB
  - 📄 tier_ranker.py 5.6 KB
- 📁 related/
  - 📄 __init__.py 0 B
  - 📄 cli_handler.py 4.5 KB
  - 📄 match_updater.py 2.5 KB
  - 📄 related_file_resolver.py 11.4 KB
  - 📄 section_iterator.py 3.5 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 feedback_collector.py 11.7 KB
  - 📄 feedback_router.py 4.3 KB
  - 📄 phase_failure_logger.py 667 B
  - 📄 project_mode.py 3.8 KB
  - 📄 scan_dispatch_config.py 1.7 KB
  - 📄 section_loader.py 968 B
  - 📄 template_loader.py 340 B
- 📁 substrate/
  - 📄 __init__.py 0 B
  - 📄 policy.py 2.7 KB
  - 📄 prompt_builder.py 6.9 KB
  - 📄 related_files.py 4.5 KB
  - 📄 schemas.py 4.5 KB
  - 📄 substrate_discoverer.py 14.4 KB
  - 📄 substrate_dispatcher.py 1.6 KB
  - 📄 substrate_state_reader.py 2.9 KB
- 📄 __init__.py 269 B
- 📄 __main__.py 96 B
- 📄 cli.py 4.8 KB
- 📄 routes.py 1.3 KB
- 📄 scan.sh 181 B
- 📄 scan_dispatcher.py 2.8 KB
- 📄 substrate.sh 186 B
📁 scripts/
- 📁 log_extract/
  - 📁 extractors/
    
    📄 __init__.py 0 B
    
    📄 artifacts.py 6.2 KB
    
    📄 claude.py 11.1 KB
    
    📄 codex.py 7.7 KB
    
    📄 common.py 3.9 KB
    
    📄 gemini.py 9.2 KB
    
    📄 opencode.py 10.9 KB
    
    📄 run_db.py 12.9 KB
  - 📄 __init__.py 0 B
  - 📄 __main__.py 120 B
  - 📄 cli.py 5.4 KB
  - 📄 correlator.py 3.9 KB
  - 📄 formatters.py 2.9 KB
  - 📄 models.py 1.4 KB
  - 📄 timeline.py 3.6 KB
  - 📄 utils.py 1.8 KB
- 📄 db.sh 37.4 KB
- 📄 workflow.sh 4.8 KB
📁 signals/
- 📁 agents/
  - 📄 impact-analyzer.md 3.3 KB
  - 📄 impact-output-normalizer.md 1.2 KB
- 📁 repository/
  - 📄 __init__.py 0 B
  - 📄 artifact_io.py 2.4 KB
  - 📄 signal_reader.py 4.1 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 blocker_manager.py 9.3 KB
  - 📄 database_client.py 3.9 KB
  - 📄 mailbox_service.py 3.5 KB
  - 📄 message_poller.py 2.6 KB
  - 📄 section_communicator.py 3.1 KB
- 📄 __init__.py 427 B
- 📄 routes.py 332 B
- 📄 types.py 3.5 KB
📁 staleness/
- 📁 agents/
  - 📄 alignment-judge.md 9.8 KB
  - 📄 alignment-output-adjudicator.md 2.4 KB
  - 📄 state-adjudicator.md 1.6 KB
- 📁 helpers/
  - 📄 __init__.py 0 B
  - 📄 content_hasher.py 1.0 KB
  - 📄 file_differ.py 794 B
  - 📄 verdict_parsers.py 2.0 KB
- 📁 service/
  - 📄 __init__.py 0 B
  - 📄 alignment_collector.py 2.5 KB
  - 📄 change_tracker.py 2.0 KB
  - 📄 freshness_calculator.py 2.7 KB
  - 📄 global_alignment_rechecker.py 5.8 KB
  - 📄 input_hasher.py 3.9 KB
  - 📄 section_alignment_checker.py 7.0 KB
- 📄 __init__.py 358 B
- 📄 routes.py 465 B
📁 taskrouter/
- 📄 __init__.py 1.6 KB
- 📄 agents.py 1.9 KB
- 📄 discovery.py 1.2 KB
- 📄 route_registry.py 5.9 KB
📁 templates/
- 📁 coordination/
  - 📄 bridge-resolve.md 449 B
  - 📄 coordinator-fix.md 2.1 KB
- 📁 dispatch/
  - 📄 agent-monitor.md 1.6 KB
  - 📄 implementation-alignment.md 2.2 KB
  - 📄 integration-alignment.md 2.2 KB
  - 📄 integration-proposal.md 8.9 KB
  - 📄 mail-instructions.md 978 B
  - 📄 section-setup.md 2.5 KB
  - 📄 signal-instructions.md 2.3 KB
  - 📄 strategic-implementation.md 7.2 KB
- 📁 scan/
  - 📄 codemap_build.md 2.9 KB
  - 📄 codemap_freshness.md 1.0 KB
  - 📄 codemap_verify.md 561 B
  - 📄 deep_analysis.md 2.1 KB
  - 📄 explore_section.md 1.4 KB
  - 📄 related_files_updater.md 779 B
  - 📄 tier_ranking.md 1.1 KB
  - 📄 validate_related_files.md 1.1 KB
- 📄 implement-proposal.md 1.1 KB
- 📄 rca-cycle.md 518 B
- 📄 research-cycle.md 682 B
📁 tools/
- 📄 extract-docstring-py 2.3 KB
- 📄 extract-docstring-sh 3.5 KB
- 📄 extract-summary-md 2.9 KB
- 📄 README.md 2.0 KB
📄 _config.py 352 B
📄 audit.md 3.9 KB
📄 baseline.md 3.1 KB
📄 constraints.md 3.2 KB
📄 containers.py 15.3 KB
📄 evaluate.md 4.4 KB
📄 implement.md 59.1 KB
📄 loop-contract.md 2.9 KB
📄 models.md 9.3 KB
📄 pyproject.toml 646 B
📄 rca.md 5.7 KB
📄 research.md 4.9 KB
📄 SKILL.md 15.6 KB

SKILL.md

---
name: agent-implementation-skill
description: Multi-model agent implementation workflow for software development. Orchestrates research, evaluation, design baseline, implementation, RCA, structured decomposition, constraint discovery, model selection, and agent-driven Stage 3 codemap exploration across external AI models (GPT, GLM, Claude). Use when implementing features through a structured multi-phase pipeline with planspace/codespace separation, dynamic scheduling, and SQLite-backed agent coordination.
---

# Development Workflow

Single entry point for the full development lifecycle. Read this file,
determine what phase you're in or what the user needs, then read the
relevant sub-file from this directory.

## Paths

Everything lives in this skill folder. WORKFLOW_HOME is: !`dirname "$(grep -rl '^name: agent-implementation-skill' ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | head -1)" 2>/dev/null`

When dispatching scripts or agents, export `WORKFLOW_HOME` with the path
above. Scripts also self-locate via `dirname` as a fallback when invoked
directly.

```
$WORKFLOW_HOME/
  SKILL.md              # this file — entry point
  implement.md          # multi-model implementation pipeline
  research.md           # exploration → alignment → proposal
  rca.md                # root cause analysis
  evaluate.md           # proposal review
  baseline.md           # constraint extraction
  audit.md              # concern-based problem decomposition
  constraints.md        # constraint discovery
  models.md             # model selection guide
  scripts/
    workflow.sh         # schedule driver ([wait]/[run]/[done]/[fail])
    db.sh               # SQLite-backed coordination database
  tools/
    extract-docstring-py  # extract Python module docstrings
    extract-summary-md    # extract YAML frontmatter from markdown
    README.md             # tool interface spec (for Opus to write new tools)
  <system>/agents/      # agent definitions distributed across system modules (scan/, proposal/, implementation/, etc.)
  templates/
    implement-proposal.md   # 10-step implementation schedule
    research-cycle.md       # 7-step research schedule
    rca-cycle.md            # 6-step RCA schedule
```

Workspaces live on native filesystem for performance, separate from project:
- **Planspace**: `~/.claude/workspaces/<task-slug>/` — schedule, state, log, artifacts, coordination database
- **Codespace**: project root — where source code lives

Clean up planspace when workflow is fully complete (`rm -rf` the workspace dir).

## Your Role

**BEFORE DOING ANYTHING ELSE**: Determine your role in the pipeline,
then read the corresponding agent definition file. Agent definitions are
distributed under system-owned directories (e.g., `$WORKFLOW_HOME/<system>/agents/<name>.md`);
the task router resolves agent files by name. Do not proceed until you have read it.

## Phase Detection

Check these in order:

1. **User explicitly requested an action** → Read the matching file
2. **Test failures need investigation** → `rca.md`
3. **Proposal exists, not yet evaluated** → `evaluate.md`
4. **Proposal evaluated, no baseline** → `baseline.md`
5. **Baseline exists, implementation needed** → `implement.md`
6. **No proposal exists** → `research.md`
7. **Something feels wrong about a change** → `constraints.md`
8. **Need to pick a model** → `models.md`
9. **Need concern-based problem decomposition** → `audit.md`

## Files

| File | What It Does |
|------|-------------|
| `research.md` | Exploration → alignment → proposal → refinement |
| `evaluate.md` | Proposal alignment review (Accept / Reject / Push Back) |
| `baseline.md` | Atomize proposal into constraints / patterns / tradeoffs |
| `implement.md` | Multi-model implementation with planspace/codespace + dynamic scheduling |
| `rca.md` | Root cause analysis + architectural fix for test failures |
| `audit.md` | Concern-based problem decomposition + alignment tracing |
| `constraints.md` | Surface implicit constraints, validate design principles |
| `models.md` | Model selection guide for multi-model workflows |

## Design Philosophy

These principles govern all pipeline behavior. Violations are alignment
failures.

1. **Alignment over audit** — Check directional coherence between adjacent
   layers ("is it solving the right problem?"), never feature coverage
   against a checklist ("is it done?"). The system is never done.
2. **Strategy over brute force** — Strategy collapses many waves of problems
   in one go. Brute force leads to countless cycles. Fewer tokens, fewer
   cycles, same quality.
3. **Scripts dispatch, agents decide** — Scripts do mechanical coordination
   (dispatch, check, log). Agents do reasoning (explore, understand, decide).
   Strategic decisions (grouping, relatedness, signal interpretation) belong
   to agents, not scripts.
4. **Heuristic exploration, not exhaustive scanning** — Build a routing map
   (codemap), then use it for targeted investigation. Never catalog every
   file. The cost of occasionally routing wrong is far less than exhaustive
   scanning.
5. **Problems, not features** — We decompose problems all the way down, then
   solve tiny problems. Proposals describe strategies, not implementations.
   We never do feature coverage because we generate as we go.
6. **Proposals must solve the same problems** — Alternative proposals are
   valid only if they solve the original problems. An optimization or
   complexity argument is an excuse. Do not introduce constraints the user
   did not specify.
7. **Accuracy over shortcuts — zero tolerance for fabrication and bypasses** —
   We accept zero tolerance for invented understanding, bypassed
   safeguards, or pipeline shortcuts that skip required grounding.
   Agents must follow the full pipeline faithfully: explore before
   proposing, propose before implementing, align before proceeding.
   Operational execution still uses proportional guardrails: the ROAL
   loop scales effort to actual risk and keeps residual risk below the
   configured threshold rather than pretending all execution can be made
   literally risk-free. "This is simple enough to skip a step" is never
   valid reasoning. When in doubt, follow the pipeline.

### Terminology Contract

- **"Audit"** only ever means alignment against stated problems and
  constraints — never feature coverage against a checklist.
- **"Alignment"** is directional coherence between adjacent layers:
  does the work solve the problem it claims to solve?
- **"Feature coverage"** is explicitly banned as a verification method.
  Plans describe problems and strategies, not enumerable features.

## The Full Lifecycle

```
Exploration → Alignment → Proposal → Review → Baseline → Implementation → Verification
  (research.md)           (evaluate.md) (baseline.md) (implement.md)    (rca.md)
```

Phases iterate: Review may loop back to Research. Implementation may
trigger tangent research cycles. Verification may reveal architectural
issues requiring RCA.

## Artifact Flow

```
[Raw Idea]
    ↓
[Exploration Notes]              ← research.md Phase A
    ↓
[Alignment Document]             ← research.md Phase B
    ↓
[Proposal]                       ← research.md Phase C
    ↓
[Evaluation Report]              ← evaluate.md (iterate if REJECT/PUSH BACK)
    ↓
[Design Baseline]                ← baseline.md (constraints/, patterns/, TRADEOFFS.md)
    ↓
[Section Files → Integration Proposals → Strategic Implementation → Code]  ← implement.md
    ↓
[Tests → Debug → Constraint Check → Lint → Commit]   ← implement.md + rca.md
```

## Workflow Orchestration

For multi-step workflows, use the orchestration system instead of running
everything from memory.

### Dispatch: All Agents via `agents`

**CRITICAL**: All step dispatch goes through `agents` via Bash.
Never use any sub-agent spawning or delegation mechanism outside this
repo's `agents` dispatch and task-submission system — external spawning
causes "sibling" errors and reliability issues. The agent runner automatically unsets
`CLAUDECODE` so sibling Claude sessions can launch.

```bash
# Sequential dispatch — model directly with prompt file
agents --model <model> --file <planspace>/artifacts/step-N-prompt.md \
  > <planspace>/artifacts/step-N-output.md 2>&1

# Agent file dispatch — agent instructions prepended to prompt
agents --agent-file "$WORKFLOW_HOME/proposal/agents/alignment-judge.md" \
  --file <planspace>/artifacts/alignment-prompt.md

# Parallel dispatch with db.sh coordination
(agents --model gpt-high --file <prompt-A.md> && \
  bash "$WORKFLOW_HOME/scripts/db.sh" send <planspace>/run.db orchestrator "done:block-A") &
(agents --model gpt-high --file <prompt-B.md> && \
  bash "$WORKFLOW_HOME/scripts/db.sh" send <planspace>/run.db orchestrator "done:block-B") &
bash "$WORKFLOW_HOME/scripts/db.sh" recv <planspace>/run.db orchestrator
bash "$WORKFLOW_HOME/scripts/db.sh" recv <planspace>/run.db orchestrator

# Codemap exploration dispatch (Opus explores the codespace)
agents --model claude-opus --project <codespace> \
  --file <planspace>/artifacts/scan-logs/codemap-prompt.md \
  > <planspace>/artifacts/codemap.md 2>&1
```

**Note**: The examples above show **script-level** dispatch — the orchestrator
launching step agents. **Nested strategic work** within step agents (e.g.,
exploration during integration proposals) uses **task submission**: agents write
structured task-request files, and the dispatcher resolves agent file + model.
See `implement.md` Stage 4-5 for task submission details.

### Schedule Templates

Pre-built schedules in `$WORKFLOW_HOME/templates/`. Each step specifies its model:
```
[wait] 1. step-name | model-name -- description (skill-section-reference)
```
- `implement-proposal.md` — full 10-step implementation pipeline
- `research-cycle.md` — external research → evaluate → propose → refine (human-facing)
- `rca-cycle.md` — investigate → plan fix → apply → verify

Note: In-runtime section research (`blocking_research_questions`) is handled
automatically through queued `research_plan` tasks within the section loop,
not through this external schedule template.

### Stage 3 Codemap Exploration

Stage 3 dispatches agents to explore and understand the codebase:
1. An Opus agent explores the codespace — reads files, follows its curiosity, builds understanding.
2. The agent writes `<planspace>/artifacts/codemap.md` capturing what it discovered.
3. Per-section Opus agents use the codemap to identify related files for each section.
4. Deep scan dispatches GLM agents to reason about specific file relevance in context.

Control and recovery:
- If `codemap.md` already exists, reuse it only if the codespace
  fingerprint is unchanged or the verifier confirms validity; otherwise
  rebuild.
- If a section already has `## Related Files`, validate the list against
  the current codemap/section content; skip only if unchanged.
- Non-zero codemap exit stops Stage 3 before section exploration.

### Model Roles

| Model | Used For |
|-------|----------|
| `claude-opus` | Section setup (excerpt extraction), alignment checks (shape/direction), decomposition, codemap exploration, per-section file identification |
| `gpt-high` | Integration proposals, strategic implementation, coordinated fixes, extraction, investigation, constraint alignment check |
| `gpt-xhigh` | Escalation-tier synthesis, deep cross-section convergence |
| `glm` | Test running, verification, quick commands, deep file analysis, semantic impact analysis |

### Prompt Files

Step agents receive self-contained prompt files (they cannot read
`$WORKFLOW_HOME`). The orchestrator builds each prompt from:
1. **Skill section text** — copied verbatim from the referenced skill file
2. **Planspace path** — so the agent can read/write state and artifacts
3. **Codespace path** — so the agent knows where source code lives
4. **Context** — relevant content from typed artifacts and `run.db`-backed context sidecars
5. **Output contract** — what the agent should return on success/failure

Written to: `<planspace>/artifacts/step-N-prompt.md`

### Workspace Structure

Each workflow gets a planspace at `~/.claude/workspaces/<task-slug>/`:
- `schedule.md` — task queue with status markers (copied from template)
- `artifacts/` — prompt files, typed JSON artifacts, context sidecars, output files, working files for steps
  - `artifacts/sections/` — section excerpts (proposal + alignment excerpts)
  - `artifacts/proposals/` — integration proposals per section
  - `artifacts/snapshots/` — post-completion file snapshots per section
  - `artifacts/notes/` — cross-section consequence notes
  - `artifacts/coordination/` — global coordinator state and fix prompts
  - `artifacts/decisions/` — accumulated parent decisions per section (from pause/resume)
  - `artifacts/parameters.json` — runtime parameters (e.g., `{"qa_mode": true}` to enable QA dispatch interception)
  - `artifacts/qa-intercepts/` — QA interceptor prompts, outputs, and rationale files (created when qa_mode is enabled)
- `run.db` — coordination database (messages, events, agent registry)
- `constraints/` — discovered constraints (promote later)
- `tradeoffs/` — discovered tradeoffs (promote later)

### Coordination System (db.sh)

SQLite-backed coordination for agent messaging. One `run.db` per pipeline
run — messages are claimed (not consumed), history is preserved, and the
database file is the complete audit trail.

```bash
# Initialize the coordination database (idempotent)
bash "$WORKFLOW_HOME/scripts/db.sh" init <planspace>/run.db

# Send a message to an agent
bash "$WORKFLOW_HOME/scripts/db.sh" send <planspace>/run.db <target> [--from <agent>] "message text"

# Block until a message arrives (agent sleeps, no busy-loop)
bash "$WORKFLOW_HOME/scripts/db.sh" recv <planspace>/run.db <name> [timeout_seconds]

# Check pending count (non-blocking)
bash "$WORKFLOW_HOME/scripts/db.sh" check <planspace>/run.db <name>

# Read all pending messages
bash "$WORKFLOW_HOME/scripts/db.sh" drain <planspace>/run.db <name>

# Agent lifecycle
bash "$WORKFLOW_HOME/scripts/db.sh" register <planspace>/run.db <name> [pid]
bash "$WORKFLOW_HOME/scripts/db.sh" unregister <planspace>/run.db <name>
bash "$WORKFLOW_HOME/scripts/db.sh" agents <planspace>/run.db
bash "$WORKFLOW_HOME/scripts/db.sh" cleanup <planspace>/run.db [name]

# Event logging and querying
bash "$WORKFLOW_HOME/scripts/db.sh" log <planspace>/run.db <kind> [tag] [body] [--agent <name>]
bash "$WORKFLOW_HOME/scripts/db.sh" tail <planspace>/run.db [kind] [--since <id>] [--limit <n>]
bash "$WORKFLOW_HOME/scripts/db.sh" query <planspace>/run.db <kind> [--tag <t>] [--agent <a>] [--since <id>] [--limit <n>]
```

**Key patterns**:
- Orchestrator blocks on `recv` waiting for parallel step results
- Step agents send `done:<step>:<summary>` or `fail:<step>:<error>` when finished
- Section-loop sends `summary:setup:`, `summary:proposal:`, `summary:proposal-align:`, `summary:impl:`, `summary:impl-align:`, `status:coordination:` messages; `complete` only on full success; `fail:<num>:coordination_exhausted:<summary>` on coordination timeout
- Mailbox is required for orchestrator/step coordination boundaries
- Codemap exploration is a single Opus agent that explores the codespace directly
- Agents needing user input send `ask:<step>:<question>`, then block on their own mailbox
- User or orchestrator can send `abort` to any agent to trigger graceful shutdown
- `agents` command shows who's registered and who's waiting — detect stuck agents

## Cross-Cutting Tools

- **audit.md** — Concern-based problem decomposition + alignment tracing
- **constraints.md** — Before implementation or when something feels wrong
- **models.md** — Which external model to use for any given task

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

agent-implementation-skill

Directory Structure

SKILL.md

Report

Notice