Concert framework operations — boot sequence, state management, next_action handoff, commit conventions, user guidance templates, spec mapping, and severity classification. Use when implementing any Concert agent or workflow. Do not use for domain-specific coding tasks unrelated to Concert orchestration.
Shared procedures for all Concert agents. Replaces duplicated logic across agent files.
Every agent reads files in this exact order to maximize LLM KV-cache prefix sharing:
.concert/state.json.concert/stage-registry.jsoncstate.json → workflow_path.claude/skills/Agent boot tiers by role:
| Role | Tiers | Agents |
|---|---|---|
| Minimal | 1 | status, delete, push |
| Orchestration |
| 1-3 |
| accept, continue, restart |
| Planning | 1-3 + upstream docs | analyst, architect, designer, planner, reviewer |
| Execution | 1, 3-4 | coder, code-reviewer, documenter, debug, fix, quick, verifier |
| Interactive | 1-3 + env check | init, reviewer, replan |
Reading state: Parse .concert/state.json. Apply defaults for missing fields (forward compatibility).
Writing state: Deep-merge updates into current state. Commit state.json after every update — crash recovery must lose at most one task of work.
Advancing stage: Look up next stage in workflow variant from stage-registry. Update pipeline.<current_stage> = "accepted", stage = <next_stage>, pipeline.<next_stage> = "pending". Write next_action hint.
Every agent writes a next_action to state.json before completing:
{
"next_action": {
"type": "run_agent", // "run_agent" | "run_workflow" | "await_user"
"target": "concert-analyst", // agent or workflow name
"context": {}, // optional key-value pairs for the target
"message": "Requirements analysis ready to begin",
},
}
Rules:
await_user → stop and show status; user must invoke next commandrun_agent → concert-continue spawns the named agentrun_workflow → concert-continue runs the named workflownext_action — never leave it staleconcert-continue reads next_action to decide what to do nextStandard next_action values by agent:
| After Agent | next_action.type | next_action.target | next_action.message |
|---|---|---|---|
| init | await_user | review | Vision ready for review |
| analyst | await_user | review | Requirements ready for review |
| architect | await_user | review | Architecture ready for review |
| designer | await_user | review | UX design ready for review |
| planner | await_user | review | Task plan ready for review |
| accept (non-interactive next) | run_agent | {next_stage_agent} | {next_stage} ready to begin |
| accept (interactive next) | await_user | {next_stage_command} | Stage accepted, user action needed |
| coder | run_agent | concert-code-reviewer | Code ready for review |
| code-reviewer (pass) | run_agent | concert-coder | Ready for next task |
| code-reviewer (fail) | run_agent | concert-coder | Revision needed |
| verifier | await_user | continue | Verification complete |
| fix | await_user | continue | Fix applied |
| debug | await_user | continue | Debug complete |
| quick | await_user | status | Quick task complete |
| delete | await_user | init | Mission deleted |
All commits use conventional format: type(scope): description
| Type | When |
|---|---|
| feat | new feature implementation |
| fix | bug fix |
| docs | documentation updates |
| chore | maintenance, state updates |
| refactor | code restructuring |
| test | test additions/modifications |
After every action, output structured guidance using templates from .concert/templates/user-guidance.md.
Required elements:
/concert:X AND (@concert-X in Copilot) syntax<stage>Look up stage metadata in .concert/stage-registry.jsonc:
| Stage | produces_spec | spec_path |
|---|---|---|
| vision | VISION-SPEC.md | .concert/VISION-SPEC.md |
| requirements | REQUIREMENTS-SPEC.md | .concert/REQUIREMENTS-SPEC.md |
| architecture | ARCHITECTURE-SPEC.md | .concert/ARCHITECTURE-SPEC.md |
| ux | UX-SPEC.md | .concert/UX-SPEC.md |
| tasks | null | — |
| execution | null | — |
Used by code-reviewer, refactorer, fix, and verifier agents:
| Level | Tag | Meaning | Blocks merge? |
|---|---|---|---|
| Critical | CRIT | Security, data loss, auth bypass | Yes |
| Major | MAJ | Broken behavior, missing validation, incorrect logic | Yes |
| Minor | MIN | Style, readability, minor improvement | No |
| Nice-to-have | NTH | Optional suggestion | No |
On failure, write to state.json:
failure block with: phase, task_file, error_type, error_summary, files_touched, last_successful_commitfailure_log[]next_action = { type: "await_user", target: "debug_or_fix", message: "Failure recorded — see state.json" }Every mission document (VISION.md, REQUIREMENTS.md, ARCHITECTURE.md, UX.md) MUST end with a structured Open Questions section using a checkbox list. This is the standardized format for all open questions:
## Open Questions
- [ ] Question or concern text here
- [ ] Another question or concern
- [x] Resolved question — resolution noted here
Rules:
- [ ]) are open questions- [x]) are resolved — include the resolution inlineDetection: To find open questions, scan for unchecked items (- [ ]) in the ## Open Questions section of each mission document. This is the ONLY method needed — no heuristic scanning for ❓, TBD, or other markers.
ALIGNMENT.md uses a similar format but with its own section name (## Open Alignment Questions) — see the reviewer agent for details.
The architect and designer agents identify technologies, services, or tools referenced in their documents that do NOT have a corresponding skill in .claude/skills/. They add a Suggested Skills section immediately BEFORE the Open Questions section:
## Suggested Skills
- **skill-name** — Target: technology/service/language. Rationale: why this skill would help downstream agents.
- **another-skill** — Target: technology/service. Rationale: brief explanation.
Rules:
.claude/skills/ before suggesting — don't suggest skills that already exist## Open Questions