Concepts

A few ideas explain how CodeOps behaves. Understanding them makes the skills predictable.

Skills vs. commands

• Skills are multi-step protocols Claude runs on request. They auto-trigger from natural language (e.g. "make a plan") and can be invoked explicitly as /codeops:<name>.
• Commands are slash commands. The core ones (/gitcm, /gitcmp, /analyze_project, /migrate_clinerules, /clean_jsdoc, /gh_issues, /gh_close) do focused jobs; the rest are thin alias commands that delegate to a parent skill in a specific mode. Aliases are manual-only — only the parent skills auto-trigger.

See the Skills overview and the Commands page.

Repo layout: flat vs. nested

CodeOps supports two on-disk layouts, and every layout-aware skill detects which one a repo uses:

• Flat layout (the default): requirements live in requirements/, plans in plans/<feature>/, and a single roadmap at plans/00-roadmap.md. This is unchanged from earlier versions and keeps working forever — no marker, no migration required.
• Nested layout: each feature owns its work under codeops/features/<feature>/ (requirements/, plans/, and a per-feature 00-roadmap.md), with a portfolio roadmap at codeops/00-roadmap.md rolling up one row per feature. It also adds a lightweight task lane (T-NN) for ad-hoc work that isn't a full feature.

A repo opts into the nested layout via a single marker file, codeops/.codeops.yml. The setup_codeops skill is the sole writer of that marker: it scaffolds a fresh skeleton or auto-migrates an existing flat repo (preview → one confirmation → git mv, history preserved). Repos without the marker stay flat, so the feature is fully non-breaking.

Progressive disclosure

Only each skill's name + description load into context up front. The full body loads when the skill is used. This is why CodeOps no longer needs the old MCP server: Claude Code keeps the context window small natively. It also means skill descriptions must stay within Claude Code's display budget (the repo's validate.sh enforces ≤ 1024 chars).

Always-on standards

The plugin bundles a single source of truth for universal coding/testing/working-style standards: standards/coding-standards.md. A SessionStart hook cats that file into the context of every new session, so the standards are always present with zero setup.

• Fires on every session start (including after /clear and context compaction).
• Read-only — the hook only reads a file shipped inside the plugin; it never writes anything.
• To turn it off, disable the plugin. There is no separate toggle.

See the summarized standards in the Reference.

Since 3.11.0 a second file is injected alongside it: standards/output-style.md, holding the reporting rules — keep answers short and tabular, recommend an effort level before starting a task, advise /compact at clean boundaries, and close with Next steps plus roadmap progress. It is separate because interaction style and code quality are different concerns; validate.sh caps the two files together, so splitting them cannot quietly grow what every session pays for.

Since 3.2.0 the injected text is a compact core (~50 lines); the complete standards live in the plugin's standards/coding-standards-full.md, which Claude reads on demand. Don't duplicate the standards in your own ~/.claude/CLAUDE.md — you'd pay the tokens twice every session. A second hook warns (never blocks) when anything other than setup_codeops edits the codeops/.codeops.yml layout marker.

Optional: execution-progress reminder hook

exec_plan's real-time update mandate can be backed by a hook if you want mechanical insurance. This is deliberately NOT shipped default-on (it fires on every Stop in every project). Opt in by adding to your project's .claude/settings.json:

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command",
      "command": "sh -c 'ls plans/*/99-execution-plan.md codeops/features/*/plans/*/99-execution-plan.md 2>/dev/null | head -1 | grep -q . && echo \"Reminder: if a task was just completed, confirm 99-execution-plan.md reflects it (two-stage marks).\" || true'" }] }]
  }
}

Rolling updates

Installs follow the marketplace's latest commit — every push is immediately installable via /plugin update, with no release/publish ceremony. The version field in plugin.json (and the CodeOps Skills Version stamps) name the release you're running; they inform, they don't gate.

The Zero-Ambiguity Gate

Several skills (make_plan, make_requirements) enforce a hard Zero-Ambiguity Gate: before any plan or requirement document is written, every gap, assumption, and open question is hunted across a fixed set of categories, compiled into an Ambiguity Register, and resolved by you — never guessed by the model. The gate opens only when every item is explicitly resolved and you have confirmed the complete register.

Since 3.2.0 the gate is single-sourced in _shared/zero-ambiguity-gate.md (the skills carry thin preambles), and two long-standing frictions are resolved: a decision may be explicitly deferred in a named form (⏸ Deferred — decision · owner · revisit-trigger) that every gate and preflight accepts — only silent deferral stays forbidden — and "accept all your recommendations" formally counts as an explicit per-item decision.

Recommendation hardening

CodeOps institutionalizes the question "are these your best recommendations?" so it runs before you ever see the answer — and so the result converges on a verified-best option instead of drifting under pressure. Before presenting a consequential recommendation the model (1) reframes — what would it recommend with 10× the budget, what would a contrarian expert push, what would make its pick obsolete; (2) passes a definition-of-done rubric — a genuinely non-obvious option considered, confidence stated, the strongest counter-argument named; and (3) discloses a Confidence: / Hardening: line so residual uncertainty is visible and you know where to push.

For high-stakes decisions — preflight findings at CRITICAL/MAJOR severity, or make_plan / make_requirements gate decisions tagged complex/sensitive — an independent challenger is spawned in a fresh context (blind to the model's pick) and reconciled, because a self-critique in the same context inherits the same blind spots. The protocol is the always-on directive plus _shared/recommendation-hardening.md; it reaches every installation automatically via rolling updates and the always-on standards.

Since 3.2.0 the ceremony is bounded: preflight spawns ONE challenger per scan (fed the whole CRITICAL/MAJOR batch plus the recon context), challenger spawns cap at two per skill run, and the Confidence:/Hardening: disclosure appears only where it carries information (Med/Low confidence, a changed pick, or high stakes).

Specification-first testing

CodeOps separates specification tests (derived from requirements/acceptance criteria — immutable oracles) from implementation tests (edge cases and internals). The enforced order is: write spec tests → confirm they fail (red) → implement → make them pass (green) → add impl tests → verify. exec_plan drives this ordering task-by-task.

Two-stage completion marks & delegation (3.2.0)

exec_plan records progress in two stages — [~] implemented (crash-safe), promoted to [x] only when verification passes — so a resumed session always re-verifies half-done work instead of trusting it. Routing-tagged tasks can be delegated to the executor subagents that now ship with the plugin (agents/plan-task-executor{,-opus}) via a defined handoff packet; executors report blockers instead of guessing and can never rewrite a failing spec test. Roadmap counters and portfolio cascades are recomputed by scripts/codeops-roadmap-sync.sh (review_roadmap uses its --check mode); a companion scripts/codeops-roadmap-compact.sh (the roadmap skill's compact action) slims a legacy roadmap back to a lean, table-only shape — stripping the old ## Notes log and flagging overstuffed cells. The lightweight task lane (mini-plans for bugfixes/chores) now exists in the flat layout too.

The pipeline

The skills compose:

grill_me → make_requirements → preflight → make_plan → preflight → exec_plan

with roadmap tracking the feature-set and techdocs keeping architecture docs current. The tutorials walk this end to end.