Agent roles and command surface
ECC presents a set of focused agent roles and slash commands that help an engineer move from a request to a safe result. Roles provide task focus, while commands provide user-facing entry points that select planning, implementation, testing, review, learning, content, or operational work. This page complements Agent catalog and prompts, Skills, contexts, and language rules, and Pi core capability bundle.
Role model
ECC assigns work to a role when a task needs a clear point of view. A role definition states the kind of work the agent should do, the conditions that should trigger it, and the limits that keep it in scope.
General-purpose roles
General-purpose roles cover the main development lifecycle. They turn an unclear request into a plan, shape architecture, write or guide tests, inspect changes, resolve build failures, and maintain supporting material.
| Role | Primary responsibility |
|---|---|
planner | Define requirements, risks, dependencies, and an implementation order before code changes. |
architect and code-architect | Make system-level decisions and produce a design that fits existing patterns. |
tdd-guide | Use tests to define behavior before implementation and check the result against coverage goals. |
code-reviewer and security-reviewer | Find quality, correctness, and security problems before delivery. |
build-error-resolver | Restore a failing build or type check with the smallest safe change. |
e2e-runner | Check critical user journeys across the running web or mobile system, while managing test stability and evidence. |
refactor-cleaner | Remove dead code or duplication while preserving behavior. |
doc-updater | Keep codemaps, guides, and other documentation aligned with the working system. |
loop-operator | Run autonomous work with checkpoints, stop rules, and recovery actions. |
These roles are intentionally narrow. For example, the planner prepares a change but waits for confirmation, while the build resolver fixes a broken build without redesigning the system. The separation lets a command combine several roles without making one role responsible for the full lifecycle.
References: agents/planner.md• L17-54 agents/tdd-guide.md• L17-49 agents/code-reviewer.md• L17-37 agents/build-error-resolver.md• L17-29 agents/e2e-runner.md• L17-32 agents/e2e-runner.md• L85-133 agents/doc-updater.md• L17-27 agents/loop-operator.md• L18-45
Specialized roles
Specialized roles apply the same lifecycle concerns to a language, framework, or business domain. Reviewers focus on the risks of a stack, and build resolvers focus on its compiler or tool chain. Domain roles cover areas such as accessibility, databases, networks, healthcare, machine learning, marketing, and open-source release safety.
| Specialist group | Role pattern | User outcome |
|---|---|---|
| Language and framework | bengali-reviewer, go-reviewer, go-build-resolver, react-reviewer, ruby-reviewer, typescript-reviewer, and similar roles | Stack- or text-aware review or recovery without changing the task into a general rewrite. |
| Product and system quality | a11y-architect, database-reviewer, performance-optimizer, rag-pipeline-reviewer, and similar roles | Focused analysis of a cross-cutting risk or product concern. |
| Research and understanding | code-explorer, docs-lookup, spec-miner, and similar roles | Evidence about an existing system, an external API, or an implied behavior. |
| Delivery and operations | agent-evaluator, commit-reviewer, gan-evaluator, harness-optimizer, opensource-forker, opensource-sanitizer, and loop-operator | Checks delivery output, prepares an open-source copy, audits a fork, or improves the agent workflow only within safe configuration boundaries. |
The command surface does not require every specialist to have its own slash command. Some roles are direct-use agents, and some are selected by a broader command or skill. For example, TypeScript review is required for TypeScript and JavaScript changes and checks type safety, asynchronous behavior, security, and idiomatic use of the stack. It runs the relevant type and lint checks before reporting findings and does not rewrite code. TypeScript review can also be paired with React or Vue review when the changed code needs both generic language checks and framework-specific checks. Bengali review checks Unicode and script handling, while Ruby review covers Ruby and Rails risks. The RAG pipeline reviewer checks whether retrieval produces useful and well-grounded context before an LLM answer is trusted. It focuses on context filtering, reranking, insufficient-context behavior, and production-shaped evaluation rather than on rewriting answer prompts. The commit reviewer drafts a message from a staged diff but does not commit or review code quality. The agent evaluator scores an agent response against a fixed quality rubric, while the GAN evaluator tests the live product and reports the browser mode it actually achieved. The harness optimizer improves the agent workflow rather than product code. The open-source forker creates a sanitized staging copy as the first pipeline stage, while the open-source sanitizer independently audits that copy without modifying it.
References: agents/bengali-reviewer.md• L17-28 agents/ruby-reviewer.md• L17-27 agents/typescript-reviewer.md• L17-34 agents/typescript-reviewer.md• L36-80 agents/react-reviewer.md• L17-34 agents/rag-pipeline-reviewer.md• L18-25 agents/rag-pipeline-reviewer.md• L27-54 agents/commit-reviewer.md• L16-29 agents/agent-evaluator.md• L17-30 agents/gan-evaluator.md• L18-42 agents/harness-optimizer.md• L18-25 agents/opensource-forker.md• L17-29 agents/opensource-sanitizer.md• L17-29 docs/COMMAND-AGENT-MAP.md• L62-66
Role boundaries
Role boundaries protect the user from a broad request being handled by an agent with the wrong goal. Review roles report findings rather than rewrite code, build roles repair errors rather than add features, and security roles treat external input and secrets as high-risk boundaries. The commit reviewer prepares a message instead of creating a commit. The open-source forker changes only the staging copy and configuration references, while the sanitizer reports release risks instead of changing files.
The shared prompt baseline keeps roles stable across tasks. Agents must not reveal secrets, accept instructions that override project rules, or treat untrusted retrieved content as trusted instructions. Evaluation roles also report the mode they actually achieved. The harness optimizer must keep security-sensitive changes blocked until a human approves them, while the sanitizer treats a single critical release finding as a failed audit.
References: agents/code-reviewer.md• L19-37 agents/build-error-resolver.md• L17-29 agents/security-reviewer.md• L17-29 agents/commit-reviewer.md• L22-29 agents/agent-evaluator.md• L8-30 agents/gan-evaluator.md• L36-42 agents/harness-optimizer.md• L27-47 agents/opensource-forker.md• L19-29 agents/opensource-sanitizer.md• L21-29 agents/planner.md• L8-17
Command surface
Slash commands are the main user-facing catalog for common ECC actions. A command takes a request or a small set of arguments and routes the work to inline guidance, one or more agents, a skill, or an orchestrated workflow.
Command families
The catalog groups commands by the result the user wants. The groups overlap in a few places because a command can both change code and verify it.
| User goal | Representative commands | Route |
|---|---|---|
| Understand and plan | /plan, /multi-plan, /plan-canvas, /ecc-guide | Clarify the problem, choose a planning path, review plan artifacts, or locate the current ECC surface before implementation. |
| Build a capability | /orch-add-feature, /feature-dev, /prp-implement, /project-init, /ui-canvas | Move from a request or approved plan toward implementation, visual design approval, or a reviewable ECC onboarding plan. |
| Change or repair behavior | /orch-change-feature, /orch-fix-defect, /orch-refine-code, /refactor-clean, /hookify | Distinguish an intentional behavior change, a defect, a behavior-neutral restructure, or a new prevention rule. |
| Test and verify | /cpp-test, /go-test, /kotlin-test, /rust-test, /react-test, /test-coverage, /checkpoint | Define or run checks that show whether behavior works. |
| Review and secure | /astra-review, /code-review, /issue-review, /review-pr, /orch-review, /security-scan, /santa-loop, /harness-audit | Inspect local changes, an issue, a pull request, the agent surface, or repository readiness and block unsafe delivery when required. |
| Recover a build | /build-fix, /cpp-build, /go-build, /kotlin-build, /rust-build, /react-build | Diagnose and repair build or type failures within the affected stack. |
| Learn and save knowledge | /learn, /learn-eval, /skill-create, /skill-health, /instinct-status, /prune | Extract reusable patterns, inspect learned instincts, check skill health, or clean up learning data within an approved scope. |
| Produce and review campaign content | /marketing-campaign | Research a product brief, set positioning, produce channel content, or audit existing copy. |
| Operate the work system | /loop-start, /loop-status, /sessions, /resume-session, /cost-report, /skill-host-compat, /token-card, /pm2, /setup-pm, /auto-update | Start, inspect, resume, measure, check host compatibility, visualize usage, or maintain work outside a single code change, including managed ECC installations. |
The command directory also includes routes for issue review, cross-provider review, learning status, skill host checks, token usage cards, and browser-based visual design. The registry provides a generated view of the surface: orchestration commands combine stages, review commands inspect work, testing commands validate behavior, and smaller build or general commands support the surrounding workflow.
References: commands/plan.md• L6-18 commands/multi-plan.md• L5-21 commands/plan-canvas.md• L6-27 commands/ecc-guide.md• L5-42 commands/project-init.md• L5-27 commands/ui-canvas.md• L1-16 commands/ui-canvas.md• L17-30 commands/issue-review.md• L6-38 commands/astra-review.md• L7-18 commands/code-review.md• L14-26 commands/harness-audit.md• L5-29 commands/learn.md• L5-12 commands/instinct-status.md• L7-15 commands/skill-health.md• L7-18 commands/cost-report.md• L6-30 commands/skill-host-compat.md• L7-18 commands/token-card.md• L7-25 commands/auto-update.md• L6-28 commands/setup-pm.md• L6-35 commands/marketing-campaign.md• L6-24 commands/skill-create.md• L7-25 docs/COMMAND-REGISTRY.json• L1-48 docs/COMMAND-REGISTRY.json• L561-662 docs/COMMAND-REGISTRY.json• L788-946
Routing relationships
Each command has a description, a broad type, its referenced agents, and its referenced skills. This gives the user a predictable route: choose the command by desired outcome, then let the command select the specialist context needed for that outcome.
The routing is not always one-to-one. A review command can use two agents when a framework review also needs language review. An orchestration command can use a skill that coordinates several stages without naming each agent in the command registry. Content commands can route a single brief to several specialists, while learning commands apply a quality and scope gate before they persist knowledge. Navigation and audit commands instead read the current catalog or deterministic audit output so their answers do not depend on stale counts. /issue-review verifies a GitHub issue against the codebase, checks duplicates and prior fixes, assigns a decision and severity, and drafts a reply. It does not write to GitHub unless the user opts in with --comment or --label; it never closes, reopens, or assigns issues. /astra-review adds a cross-provider route: it sends a selected diff to GPT-6-Astra through Codex, then verifies and fixes confirmed findings through a bounded review cycle. /ui-canvas routes a component mockup into a browser editing surface, keeps user feedback tied to the preview, and uses the finished export as the input for real implementation. The command-to-agent map is useful for discovery, while the command file and its referenced skill explain the actual workflow.
This diagram shows how a user goal selects a command and then reaches the context or specialists needed to produce a result.
flowchart LR
Request[User request] --> Choice{Desired outcome}
Choice --> Plan[Planning commands]
Choice --> Build[Implementation commands]
Choice --> Test[Testing commands]
Choice --> Review[Review commands]
Choice --> Learn[Learning commands]
Choice --> Content[Content commands]
Choice --> Operate[Operational commands]
Plan --> Context[Agent and skill context]
Build --> Context
Test --> Context
Review --> Context
Learn --> Context
Content --> Specialists[Delegated specialists]
Operate --> Context
Specialists --> Result[Campaign assets or review]
Context --> Result2[Plan, code, findings, test result, knowledge, or run state]
The registry is generated from the command directory. It finds known agent and skill names in command text, so a routing entry is only useful when the referenced role or skill exists in the active catalog.
References: commands/issue-review.md• L26-42 commands/astra-review.md• L7-18 commands/astra-review.md• L36-98 commands/ui-canvas.md• L17-30 commands/learn.md• L38-53 commands/skill-create.md• L54-91 commands/marketing-campaign.md• L112-119 commands/ecc-guide.md• L22-42 commands/harness-audit.md• L17-25 docs/COMMAND-AGENT-MAP.md• L1-3 scripts/…/generate-command-registry.js• L78-111 scripts/…/generate-command-registry.js• L139-153
Lifecycle paths
The strongest command paths place a gate between stages. Planning commands protect the codebase from premature edits, test-driven commands make expected behavior explicit, and review commands provide a second check before delivery.
For a new capability, /orch-add-feature is the clearest end-to-end route. It researches and plans first, waits at a plan gate, applies TDD, runs review, and waits again before commit. Defect work follows a different path: /orch-fix-defect proves the problem with a failing regression test before it fixes the behavior. A behavior-neutral restructure uses /orch-refine-code, which relies on existing green tests rather than adding new behavior. /plan-canvas provides a visual approval path for plan artifacts when typed confirmation is not the preferred interface. /ui-canvas provides a related visual path for component work: it opens a mockup, lets the user edit and discuss it, waits for Save and Finish, and then uses the exported design to guide implementation.
This diagram shows the main gated paths for new work, defect work, and behavior-neutral restructuring.
flowchart TD
Start[Task request] --> Classify{Task kind}
Classify --> New[New capability]
Classify --> Defect[Broken behavior]
Classify --> Refine[Behavior-neutral restructure]
New --> PlanGate[Research and plan approval]
PlanGate --> TDD[Tests and implementation]
Defect --> Red[Failing regression test]
Red --> Fix[Fix to green]
Refine --> Green[Confirm existing tests are green]
Green --> Restructure[Small restructuring steps]
TDD --> Review[Review]
Fix --> Review
Restructure --> Review
Review --> CommitGate[Commit approval]
These paths are choices rather than a rule that every command must follow. A direct review or build command is appropriate when the work is already at that stage.
References: commands/orch-add-feature.md• L5-36 commands/orch-fix-defect.md• L5-38 commands/orch-refine-code.md• L5-39 commands/plan.md• L6-18 commands/plan-canvas.md• L15-27 commands/ui-canvas.md• L17-30
Operational paths
Operational commands manage the state around development rather than the product code itself. Loop commands use explicit patterns, checkpoints, and stop conditions. Session commands preserve context for later work, while service, cost, audit, package-manager, compatibility, usage-card, and update commands help prepare or inspect the local environment.
/loop-start prepares a managed loop and checks the repository state, tests, hook profile, and stop condition before it prints launch commands. /resume-session restores the most recent eligible session or a user-selected session file. It reports what it loaded and waits for the user before starting work. /sessions gives operators a broader view of session history through listing, loading, aliases, and session metadata. Its info view also exposes project, branch, and worktree context for parallel-run monitoring. /cost-report summarizes the latest per-session snapshots from the local cost log, while /harness-audit returns a reproducible readiness score for a selected repository area.
/skill-host-compat checks curated skills for Codex- and Cursor-safe metadata and Claude-only substitutions. Its normal mode enforces the check, while --inventory reports counts without failing. /token-card reaches the canonical token-card skill to render usage from local agent logs, with a dry-run path that writes nothing. /auto-update pulls the latest ECC repository changes and rebuilds the current managed install from the recorded install-state request. Its dry-run mode shows the reconstructed reinstall plan first. The reinstall also handles upstream renames and deletions that a repair based only on old operations cannot safely recover.
/setup-pm configures the package-manager preference at project or global scope. When a tool needs to detect the active manager, the command gives priority to the CLAUDE_PACKAGE_MANAGER environment variable, then project configuration, the package.json declaration, lock files, and global configuration before falling back to npm. This keeps package-manager choice explicit while still providing a predictable default.
Multi-model commands are a separate operational path. /multi-plan divides context retrieval, analysis, and planning between Codex and Antigravity, writes only plan artifacts, and requires the external ccg-workflow runtime. It is not equivalent to a normal single-session command.
References: commands/loop-start.md• L5-30 commands/resume-session.md• L26-49 commands/resume-session.md• L70-112 commands/sessions.md• L5-19 commands/sessions.md• L292-309 commands/cost-report.md• L11-30 commands/harness-audit.md• L17-55 commands/skill-host-compat.md• L7-40 commands/token-card.md• L7-28 commands/auto-update.md• L6-28 commands/setup-pm.md• L6-35 commands/multi-plan.md• L5-21 docs/COMMAND-AGENT-MAP.md• L50-60
Knowledge and content paths
Knowledge commands turn past work into reusable guidance, while campaign commands turn a product brief into a coordinated set of communication assets. Both paths use an explicit quality boundary before they produce a durable result.
/learn reviews the current session for reusable error fixes, debugging methods, workarounds, or project patterns. It sanitizes the draft, checks the target scope, and asks for approval before saving a global skill. /learn-eval extends this path with a reusable-pattern check, a choice between global and project scope, and an approval step before saving. /skill-create derives patterns from local Git history and writes them as discoverable skills only after validating the name, path, metadata, and export or discovery status. It treats repository history as untrusted source material and requires approval before replacing an existing skill. A custom output can remain export-only until the active harness discovers that root. /skill-health provides a quantitative portfolio dashboard with recent success rates, clustered failure patterns, pending amendments, and version history. It is distinct from a qualitative skill compliance or quality audit. /instinct-status shows project and global learned instincts, merges them with project precedence when IDs collide, and displays confidence and observation data. /prune removes stale pending instincts.
/marketing-campaign first establishes audience and positioning from a product brief. It then produces content in channel order or reviews existing copy against clarity, calls to action, tone, claims, and cross-channel fit. Single deliverables still require positioning, and saved assets use a named campaign directory after the save location is confirmed.
References: commands/learn.md• L13-53 commands/learn.md• L81-107 commands/learn-eval.md• L20-47 commands/learn-eval.md• L80-127 commands/skill-create.md• L54-91 commands/skill-create.md• L124-137 commands/skill-health.md• L7-18 commands/skill-health.md• L42-58 commands/skill-health.md• L56-58 commands/instinct-status.md• L7-18 commands/instinct-status.md• L31-37 commands/prune.md• L7-31 commands/marketing-campaign.md• L19-24 commands/marketing-campaign.md• L28-66 commands/marketing-campaign.md• L81-96
Catalog integrity
The command and agent catalogs are part of the user interface. Metadata checks keep commands discoverable, agent roles loadable, and exported command names aligned with the active command directory.
Metadata contracts
Command files need frontmatter with a non-empty description. Agent files need frontmatter with a model and tools field, and the model must be one of the supported tiers. These checks prevent a command or role from silently disappearing because its entry metadata cannot be read.
The exported agent.yaml command list must match the active commands/ directory. Retired legacy slash shims stay in an opt-in archive rather than appearing in the default surface, which keeps old entry points from being mistaken for current commands.
References: tests/…/command-frontmatter.test.js• L25-53 scripts/…/validate-agents.js• L63-110 tests/…/agent-yaml-surface.test.js• L81-110
Registry freshness
The command registry is a generated view of command descriptions, broad types, agent references, and skill references. When a command or its routing text changes, the registry must be regenerated so catalog consumers do not read an old route.
The registry writer uses stable JSON output and the check mode compares the stored file with the generated result. This makes stale routing data a clear validation failure instead of a silent documentation drift.
References: scripts/…/generate-command-registry.js• L171-229 tests/…/command-registry.test.js• L75-136
Change checklist
When these files or sections are changed, remember to consider these:
- When adding or renaming a role reference in a command, check that the role name still matches an active agents/*.md file and regenerate docs/COMMAND-REGISTRY.json.
- When adding or removing a command, update the agent.yaml export list and confirm that retired legacy shims remain outside the default surface.
- When changing a command's frontmatter description, check both command discovery and the generated registry description.
- When changing a multi-stage workflow, preserve its approval gates and keep the command's stated task kind aligned with the orchestrator skill.
- When changing a stack-specific review or test command, check the paired language or framework role and its related skill references.
- When changing
/ui-canvas, preserve the hand-edit, feedback acknowledgement, Save and Finish, and export-to-implementation boundary. - When changing
/plan,/multi-plan, or/plan-canvas, preserve the boundary between plan creation, visual or typed approval, and implementation. - When changing
/review-pr,/code-review,/issue-review,/orch-review,/astra-review, or/santa-loop, keep their distinct review modes, external-sharing consent, and verdict gates aligned so users do not select the wrong review depth. - When changing
/learn,/learn-eval,/skill-create,/skill-health,/instinct-status, or/prune, preserve the scope decision, safe path validation, explicit persistence approval, and discoverability or cleanup rules. For/skill-create, also keep the generated skill name equal to its directory and frontmatter name, and keep export-only output distinct from an active skill root. - When changing
/resume-session, preserve the distinction between automatic candidate selection and an explicit file path, as well as the wait-before-work boundary. - When changing
/loop-start, keep test readiness, hook-profile checks, and explicit stop conditions before loop launch. - When changing
/auto-update, preserve the recorded install-state input, the dry-run preview, and the reinstall behavior needed for upstream renames and deletions. - When changing
/marketing-campaign, keep the positioning prerequisite aligned with the delegated specialists, the campaign asset naming convention, and the confirmed save location. - When changing
/ecc-guide, keep answers based on the live repository and catalog rather than hard-coded counts, and preserve links to canonical surfaces. - When changing
/security-scan,/hookify, or/harness-audit, keep scanner or audit output as the source of truth and require approval before applying guarded changes. - When changing
/sessions,/cost-report,/skill-host-compat, or/token-card, preserve their distinct local data source, host projection, or canonical skill boundary. - When changing
/setup-pm, preserve the precedence between environment, project, package metadata, lock-file, and global settings, as well as the npm fallback. - When changing
e2e-runner, preserve the preferred browser path, the Playwright fallback, the separate mobile setup needs, and the distinction between replayed and live agent steps when checking flakiness. - When changing
rag-pipeline-reviewer, preserve production-path evaluation, context filtering, reranking, insufficient-context handling, the minimum metric set, and specialist handoffs. - When changing
gan-evaluatororharness-optimizer, preserve truthful evaluation-mode reporting and the human-approval block for security-sensitive harness changes. - When changing
bengali-reviewer,ruby-reviewer,typescript-reviewer,commit-reviewer,opensource-forker, oropensource-sanitizer, preserve their narrow review, fork, or audit scope and their stated output or approval rules.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A command names an agent or skill that is not in the active catalog | The command still appears available but cannot route to the intended specialist | Generate the registry and verify references against known agent and skill names. |
| A command file is added without a description frontmatter field | Command discovery and registry descriptions become incomplete | Run the command frontmatter validation. |
agent.yaml and commands/ diverge | An install or export surface omits a command or exposes the wrong one | Run the agent YAML surface check. |
| A command or routing reference changes without regenerating the registry | Consumers use stale type, agent, or skill information | Run registry check mode and rewrite the registry when it reports drift. |
/ecc-guide answers from hard-coded or stale catalog data | Users choose a surface that is no longer present or miss a current one | Read the live repository and catalog before answering. |
| Work starts before the plan gate or commit gate | The workflow loses its safety boundary and may change or commit code without approval | Use the gated orchestration commands as documented. |
/ui-canvas acknowledges edits that were not incorporated or implements before Save and Finish | User changes can be lost or an unapproved mockup can reach the real component | Keep feedback IDs tied to incorporated exports and wait for the finish event before implementation. |
/multi-plan runs without the external ccg-workflow runtime | The dual-model planning path cannot start its required model sessions | Provision the runtime before selecting the multi-model path, or use /plan. |
/loop-start finds failing tests, a disabled hook profile, or no stop condition | The managed loop can start without a reliable safety boundary | Keep the required pre-launch checks enabled and select a stop condition. |
/auto-update runs against the wrong root or without a dry-run review | The wrong managed target can be changed, or an unexpected reinstall can mutate the environment | Resolve the intended ECC root, use the recorded install state, and preview with --dry-run when needed. |
/resume-session finds no eligible session or receives a missing explicit path | The user cannot recover the intended context and may start from an incomplete state | Report the precise missing or invalid source and stop without substituting another explicit file. |
| A learning command saves outside its approved scope or without approval | Repository or global knowledge can receive unsafe, misplaced, or unwanted content | Validate the slug and target root, show the sanitized draft, and require confirmation before persistence. |
/skill-create writes to an unconfigured custom output and reports the skill as active | The generated skill exists as an export but is not discovered by the harness | Verify the configured skill root and label other custom output as export-only. |
| A generated skill replaces an existing target without approval | Existing team guidance can be lost or changed silently | Show the diff and require explicit overwrite approval before atomic replacement. |
/marketing-campaign produces a single deliverable before positioning is defined | The asset can conflict with the campaign angle or other channels | Run full mode or provide the positioning angle before requesting the deliverable. |
| A hookify rule is written before the proposed behavior and action are approved | A broad block or warning can change future sessions without a deliberate user decision | Present the matcher, event, and action before writing the local rule. |
| A live evaluator cannot use its requested browser tools but reports a live test | A static or degraded check is mistaken for a full product evaluation | Record the achieved mode and report the fallback before scoring. |
| An E2E run uses replayed agent steps as proof of current UI behavior | A changed or unstable flow can appear reliable because live model actions were not repeated | Use live runs with --no-cache when checking current behavior or flakiness. |
| A mobile E2E setup keeps the example Settings app or lacks an installed target build | The test does not exercise the intended app or cannot start on the device | Set the target bundle and app path, then install the build before running. |
| A RAG pipeline forwards raw top-k context without filtering or reranking | Tangential or repeated text can crowd out evidence and produce weakly grounded answers | Check the final assembled context for relevance filtering, reranking, and an insufficient-context fallback. |
| A RAG evaluation uses only a low-level search benchmark or omits a baseline and required metrics | High search scores can hide lost topics, poor source mix, or regressions in the production path | Evaluate production-shaped inputs with faithfulness, context recall, context precision, slices, and regression thresholds. |
| A harness change weakens a safety control or expands secret access | The agent workflow becomes unsafe even if quality scores improve | Keep the status blocked until a human explicitly approves the security-sensitive change. |
/astra-review sends code without the required consent or cannot complete its external review | Private code may leave the machine without deliberate approval, or an incomplete review may be treated as a pass | Preview the scope, require the OpenAI consent flag, and stop on an error or unresolved high-severity finding. |
/issue-review treats issue text as instructions or posts without opt-in | Untrusted content can drive unsafe actions, or a draft can be published unexpectedly | Treat issue text as data, show exact comments or labels first, and require the matching flag. |
/cost-report sums every snapshot for a session | Reported spend is multiplied by the number of stop events | Select the latest row per session_id before aggregation. |
/token-card bypasses its canonical skill or writes during a dry run | Usage output can drift from the supported workflow or modify the worktree unexpectedly | Follow the token-card skill and keep --dry-run write-free. |
| A host-compatibility check is treated as an inventory-only result | Claude-only substitutions or unsafe frontmatter can reach Codex or Cursor | Use the normal validator for enforcement and reserve --inventory for counts. |
| Package-manager settings conflict across scopes | Install or run commands can use a different tool than the project expects | Apply the documented precedence and inspect the result with /setup-pm detection. |
| A snapshot operation runs on storage without hardlink support | Skill version history cannot be created or changed safely | Use hardlink-capable storage for snapshot creation and rollback. |
| The open-source forker leaves a secret, report, or source history in the staging copy | Private data or internal history can reach the public release | Strip or parameterize sensitive values, exclude reports from the initial commit, and create a fresh single-commit history. |
| The open-source sanitizer treats warnings or unreadable files as a plain pass | A release can contain unresolved configuration risks or files no text scan covered | Report PASS WITH WARNINGS for warnings or unreadable files and require human review. |
| A Bengali, Ruby, TypeScript, commit, or open-source audit role expands into unrelated work | The review misses its required risk focus or changes files outside its contract | Keep the specialist scope and approval criteria explicit. |
Key files
| File | Why to read it |
|---|---|
| docs/COMMAND-AGENT-MAP.md | Quick map of user commands to primary agents, skills, and non-slash operational surfaces. |
| docs/COMMAND-REGISTRY.json | Current generated catalog of commands, descriptions, broad types, and routing references. |
| agent.yaml | Export declaration for the active command surface and shared skill catalog. |
| agents/planner.md | Example of a planning role with clear scope and approval-oriented behavior. |
| agents/code-reviewer.md | Example of a general review role and its quality and security focus. |
| agents/tdd-guide.md | Example of the test-first role used by implementation and language test workflows. |
| agents/e2e-runner.md | End-to-end role for critical web or mobile journeys, artifact capture, and flaky-test control. |
| agents/rag-pipeline-reviewer.md | Retrieval review role for grounded context, production-shaped evaluation, and handoffs. |
| agents/doc-updater.md | Documentation role that keeps codemaps and guides aligned with the system. |
| agents/agent-evaluator.md | Quality role that scores agent output and separates evaluation from task execution. |
| agents/gan-evaluator.md | Live-product evaluation role that scores the running application and reports the achieved test mode. |
| agents/harness-optimizer.md | Harness role that improves agent configuration through evals and preserves safety gates. |
| agents/bengali-reviewer.md | Script-aware review role for Bengali text processing and display. |
| agents/ruby-reviewer.md | Ruby and Rails review role for code, security, data access, and test quality. |
| agents/typescript-reviewer.md | TypeScript and JavaScript review role for type safety, async correctness, security, and stack-specific quality. |
| agents/commit-reviewer.md | Commit-message role that turns a staged diff into a history-aligned proposal without committing. |
| agents/opensource-forker.md | First pipeline role that creates an open-source-ready staging copy and records its changes. |
| agents/opensource-sanitizer.md | Read-only release audit role for secrets, private data, internal references, and dangerous files. |
| commands/plan.md | Single-model planning path with an explicit confirmation boundary. |
| commands/multi-plan.md | External multi-model planning path that writes plans but not production code. |
| commands/plan-canvas.md | Visual plan review path that turns an approval verdict into a plan gate. |
| commands/ui-canvas.md | Browser-based component design path that carries user edits into implementation. |
| commands/issue-review.md | Issue verification path that drafts findings and optional GitHub comments or labels. |
| commands/astra-review.md | Cross-provider review path with consent, bounded repair rounds, and a machine-readable verdict. |
| commands/code-review.md | Local and pull-request checklist review with severity-based delivery decisions. |
| commands/review-pr.md | Multi-agent pull-request review path with confidence filtering. |
| commands/orch-review.md | Adversarially verified workflow review with blocking and advisory findings. |
| commands/santa-loop.md | Dual-review convergence path that requires independent approval before push. |
| commands/loop-start.md | Managed autonomous-loop setup with safety checks and stop conditions. |
| commands/sessions.md | Session history, metadata, aliases, and worktree context for recovering or monitoring work. |
| commands/instinct-status.md | Learned-instinct status view across project and global scopes. |
| commands/cost-report.md | Local cost summary that reduces cumulative session snapshots before aggregation. |
| commands/skill-health.md | Quantitative skill portfolio dashboard for success, failure, amendments, and versions. |
| commands/skill-host-compat.md | Host compatibility check for Codex and Cursor skill projections. |
| commands/token-card.md | Compatibility entry point for rendering local agent usage as a repository asset. |
| commands/auto-update.md | Managed ECC update path that previews and reapplies the recorded install request. |
| commands/setup-pm.md | Package-manager configuration path and the precedence used to detect the active manager. |
| commands/learn.md | Session-to-skill learning path with guarded global persistence. |
| commands/skill-create.md | Git-history path that generates sanitized, validated, discoverable or export-only skills. |
| commands/marketing-campaign.md | Campaign path from product brief and positioning to content production or copy review. |
| commands/ecc-guide.md | Current navigation path for agents, skills, commands, hooks, and install surfaces. |
| commands/security-scan.md | AgentShield path for prioritized security findings and safe fixes. |
| scripts/…/generate-command-registry.js | Source of the registry's routing and freshness rules. |
| tests/…/agent-yaml-surface.test.js | Contract for the exported command surface and retired shims. |