using-anionzo

name	using-anionzo
description	Bootstrap meta-skill for the anionzo agentic development ecosystem. Load first on any anionzo project. Lists all 9+2 skills with routing logic, session scout/bootstrap, small-change vs standard-feature vs high-risk mode selection, go mode (full-auto pipeline with 4 human gates), priority rules, and state resume. Invoke when starting a new session, choosing which skill to use, running the full pipeline end-to-end, or resuming after a handoff.
metadata	{"version":"2.2","ecosystem":"anionzo","dependencies":[{"id":"nodejs-runtime","kind":"command","command":"node","missing_effect":"unavailable","reason":"The bootstrap scripts run in Node.js."},{"id":"beads-cli","kind":"command","command":"br","missing_effect":"degraded","reason":"Bead planning and execution flows rely on br."},{"id":"beads-viewer","kind":"command","command":"bv","missing_effect":"degraded","reason":"Triage and readiness checks rely on bv robot commands."},{"id":"cass-cli","kind":"command","command":"cass","missing_effect":"degraded","reason":"Session-history lookups are part of the default workflow."},{"id":"cass-memory","kind":"command","command":"cm","missing_effect":"degraded","reason":"Memory context retrieval is part of the default workflow."},{"id":"gkg","kind":"mcp_server","server_names":["gkg"],"config_sources":["repo_codex_config","global_codex_config","plugin_mcp_manifest"],"missing_effect":"degraded","reason":"Planning and exploration depend on gkg-backed architecture intelligence."},{"id":"agent-mail","kind":"mcp_server","server_names":["mcp_agent_mail"],"config_sources":["repo_codex_config","global_codex_config"],"missing_effect":"degraded","reason":"Swarming and worker coordination rely on Agent Mail."}]}

using-anionzo

Bootstrap meta-skill. Load this first. It tells you which skill to invoke next and how the ecosystem chains together.

---

Purpose

Bootstrap anionzo ecosystem projects. Load this skill first on any anionzo project — it lists all skills, provides routing logic, and starts the go-mode pipeline.

When To Use

Load this skill when:

• Starting a new anionzo session
• Choosing which skill to invoke next
• Running the full pipeline end-to-end
• Resuming after a handoff
• Setting up a new anionzo project

When NOT to use: Non-anionzo projects (use using-skills instead).

Output Format

Skill catalog: all available skills with routing logic Routing decision: recommended next skill and mode Bootstrap status: .anionzo/ and STATE.md readiness

Done Criteria

• Skill catalog presented with routing guidance
• Correct skill and mode identified for the request
• Bootstrap complete (or bootstrap initiated if needed)
• Go-mode pipeline ready if full pipeline requested

Plugin Onboarding

Before any normal bootstrap, verify that the current machine has Node.js available and that the current repo is onboarded for the Anionzo plugin.

Run node --version first.

• If node is missing or too old: stop immediately, tell the user Anionzo requires Node.js 18+, and ask them to install or upgrade Node before continuing.

Then run node scripts/onboard_anionzo.mjs --repo-root <repo-root> from this skill directory and inspect the JSON result.

• If status = "up_to_date": proceed immediately.
• Always inspect details.dependency_warning in the JSON output:
  • If status = "warning", treat bootstrap as non-blocking but degraded and read the summary message.
  • Confirm which skills are affected plus the explicit split:
    • Missing commands: ...
    • Missing MCP server configuration: ...
  • Cross-check the same command-vs-MCP wording boundary against the session-start note and scout output.
• If onboarding is missing or stale:
  • summarize what the script wants to create or update
  • if status = "missing_runtime": stop, tell the user Anionzo requires Node.js 18+, and ask them to install or upgrade Node before continuing
  • if requires_confirmation = true, explain that an existing compact_prompt was found and Anionzo will preserve it unless the user explicitly approves replacement
  • ask before making repo changes
  • after approval, run node scripts/onboard_anionzo.mjs --repo-root <repo-root> --apply
  • only use --allow-compact-prompt-replace when the user explicitly approved replacing the repo's existing compaction prompt

Onboarding installs or updates:

• root AGENTS.md from the plugin's AGENTS.template.md
• repo-local .codex/config.toml
• repo-local .codex/hooks.json
• repo-local .codex/hooks/anionzo_*.mjs
• repo-local .codex/anionzo_status.mjs
• repo-local .codex/anionzo_state.mjs
• .anionzo/onboarding.json
• .anionzo/state.json

If onboarding is not complete, do not continue into the rest of the Anionzo workflow.

---

Session Scout

After onboarding succeeds, use the repo-local scout command as the first quick orientation step whenever it is available:

node .codex/anionzo_status.mjs --json

The scout is read-only. It summarizes:

• onboarding health
• gkg readiness for this repo
• .anionzo/state.json
• .anionzo/STATE.md
• .anionzo/HANDOFF.json
• recommended next reads/actions

Use it to get the current truth quickly, then open the deeper files it points to.

gkg Readiness Is Part of Session Start

Treat gkg as a first-class discovery dependency for supported repositories.

After reading the scout output:

• If gkg readiness says the repo is unsupported: do not force gkg. Note the fallback and use grep/file inspection.
• If the repo is supported and server_reachable = false: make gkg ready before planning by running gkg index <repo-root> and then gkg server start.
• If the repo is supported and project_indexed = false: stop the server if needed, run gkg index <repo-root>, then start the server again.
• If both server and index are ready: downstream skills should assume gkg is the default architecture-discovery path, not an optional nice-to-have.

Supported repo languages for this bootstrap are: Ruby, Java, TypeScript / JavaScript, Kotlin, and Python. Use the scout's supported_languages and primary_supported_language fields instead of guessing from the prompt.

---

Dependency Declaration Contract

Every packaged Anionzo skill must make its dependency posture explicit. There are only three valid states:

1. Command-backed skill — declare each required CLI under metadata.dependencies with kind: command, the binary name in command, a truthful missing_effect, and a short reason.
2. MCP-backed skill — declare each required MCP server under metadata.dependencies with kind: mcp_server, the expected server_names, the supported config_sources, a truthful missing_effect, and a short reason.
3. Dependency-free packaged skill — declare metadata.dependencies: [] to say the skill was reviewed and does not rely on first-class external tools.

Do not leave a packaged skill with undeclared dependency posture. A missing declaration is treated as an uncovered inventory gap, not as an implicit dependency-free skill.

When updating or adding packaged Anionzo skills, keep the docs and the live report aligned by running:

• node plugins/anionzo/skills/using-anionzo/scripts/test_onboard_anionzo.mjs
• bash scripts/check-markdown-links.sh plugins/anionzo/skills/using-anionzo/SKILL.md
• bash scripts/sync-skills.sh --dry-run

These checks are the package-wide contract: the report should stay fully covered, the docs must stay portable, and the synced skill bundle must reflect the same declaration rules.

---

Skill Catalog

#	Skill	One-line description	Load when...
1	anionzo:using-anionzo	This file. Routing, go mode, red flags.	Starting any session
2	anionzo:exploring	Identify gray areas, lock decisions → CONTEXT.md	Feature request is vague or new; "what exactly should this do?"
3	anionzo:planning	Research + synthesis → phase-plan.md, then current-phase contract/story map + beads	Decisions are locked (CONTEXT.md exists); ready to show the full phase/story breakdown and prepare the next phase
4	anionzo:validating	Verify the current phase contract, story map, and bead graph before execution	The phase plan is approved and the current phase has stories and beads; need to prove this phase is actually execution-ready
5	anionzo:swarming	Launch+tend worker pool via Agent Mail + bv	Beads are validated; ready to execute at scale
6	anionzo:executing	Single worker loop: priority → reserve → implement bead → close → loop	Spawned by swarming; one agent, self-routing from the live graph
7	anionzo:reviewing	5 parallel review agents (P1/P2/P3) + artifact verification + UAT	Execution complete; need quality gate before merge
8	anionzo:compounding	Capture learnings → history/learnings/ → critical-patterns.md	Feature shipped; extract patterns/decisions/failures for future runs
9	anionzo:writing-anionzo-skills	TDD-for-skills: RED-GREEN-REFACTOR + persuasion psychology	Improving or creating anionzo skills themselves
10	anionzo:debugging	Root-cause analysis for blocked beads and execution failures	Agent stuck, bead blocked, unexpected error
11	anionzo:gkg	Codebase intelligence via gkg MCP tools after readiness is green	Need deep codebase understanding before planning

---

Routing Logic

Given a user request, determine the working mode first, then the first skill.

Mode selection

Mode	Use when...	Notes
small_change	≤3 files, no new API/data model, LOW risk, no gray areas	Lightweight planning and validating, but still no skipping validating
standard_feature	Normal feature or refactor with clear value but moderate scope	Default mode for most Anionzo work
high_risk_feature	Cross-cutting, high-blast-radius, or architecture-sensitive work	Use deeper planning review and explicit spikes for risky items

First-skill routing

Given a user request, determine which skill to invoke first:

Request type	First skill	Notes
Vague/new feature ("build X")	anionzo:exploring	Always start here if gray areas exist
Research task ("investigate Y")	anionzo:planning	Skip exploring only if scope is fully clear
"Just fix this" / small change	anionzo:planning	Route in small_change mode
"Review my code"	anionzo:reviewing	Load directly
"What did we learn?" / "Capture learnings"	anionzo:compounding	Load directly
"Improve anionzo itself"	anionzo:writing-anionzo-skills	Load directly
Agent stuck / error	anionzo:debugging	Load directly
"Run the full pipeline" / /go	Go Mode (below)	Chain all skills
Resuming a session	Resume Logic (below)	Check HANDOFF.json first

When in doubt: invoke anionzo:exploring first. The cost of over-exploring is low; the cost of executing a misunderstood feature is high.

---

State Bootstrap

On every session start, before doing anything else:

0. Confirm Anionzo onboarding is current via .anionzo/onboarding.json
   → If missing or stale: return to Plugin Onboarding above

0.5. If .codex/anionzo_status.mjs exists: run `node .codex/anionzo_status.mjs --json`
   → Use the scout output to decide which files to open next

0.6. Check `gkg_readiness` from the scout output
   → Unsupported repo: note the fallback and continue without gkg
   → Supported repo + server/index not ready: make gkg ready before planning or deep discovery
   → Supported repo + ready: planning should use gkg MCP tools as the default discovery path

1. Check for .anionzo/ directory in project root
   → If missing: mkdir -p .anionzo/ and create defaults below
   
2. Check .anionzo/state.json
   → If missing: create with defaults:
     {
       "schema_version": "1.0",
       "phase": "idle",
       "approved_gates": {
         "context": false,
         "phase_plan": false,
         "execution": false,
         "review": false
       }
     }

3. Check .anionzo/STATE.md
   → If missing: create with template:
     # STATE
     focus: (none)
     phase: idle
     last_updated: <date>
   
4. Check .anionzo/HANDOFF.json
   → If exists → go to Resume Logic below
   → If missing → proceed normally
   
5. Check .anionzo/config.json
   → If missing: create {} (all features enabled by default — absent=enabled)

6. Check for history/learnings/critical-patterns.md
   → If exists: read it now. These are mandatory context for all subsequent skills.

---

Resume Logic

If .anionzo/HANDOFF.json exists:

1. Read HANDOFF.json (and .anionzo/state.json if present)
2. Extract: { phase, skill, feature, context_pct, next_action, beads_in_flight }
3. Present to user:
   "Session paused at [phase] during [feature].
    Last action: [last_action]
    Suggested: [next_action]
    Resume? (yes / no / show state)"
4. If yes → load the skill named in HANDOFF.json and continue
5. If no  → ask what to work on instead
6. Do NOT auto-resume without user confirmation

---

Go Mode (Full Pipeline)

Go mode chains all skills end-to-end with exactly 4 human gates. Load references/go-mode-pipeline.md for the complete step-by-step sequence.

Trigger: User says /go [feature], "run the full pipeline", or "go mode".

The 4 gates — never skip these:

GATE 1 (after exploring):
  Present history/<feature>/CONTEXT.md to user.
  Ask: "Decisions locked. Approve CONTEXT.md before planning?"
  HARD-GATE: do not invoke planning until user approves.

GATE 2 (after whole-feature planning):
  Present: full phase list, stories inside each phase, and which phase will be prepared first.
  Ask: "Phase breakdown is ready. Approve phase-plan.md before current-phase preparation?"
  HARD-GATE: do not prepare the current phase or create beads until user approves.

GATE 3 (after validating the current phase):
  Present: phase exit state, story count, bead count, risk summary, spike results.
  Ask: "Current phase verified. Approve execution?"
  HARD-GATE: do not invoke swarming until user approves.

GATE 4 (after reviewing):
  Present: P1 count, P2 count, P3 count.
  If P1 > 0: "P1 findings block merge. Fix before proceeding?"
  If P1 = 0: "Review complete. Approve merge?"
  HARD-GATE: do not merge or close epic until user responds.

Go mode sequence:

exploring → [GATE 1] → planning (whole feature) → [GATE 2]
         → planning (current phase prep) → validating → [GATE 3]
         → swarming (+ executing ×N)
         → if more phases remain: planning (next phase prep) and repeat
         → if final phase complete: reviewing → [GATE 4] → compounding → DONE

---

Mode Guidance

small_change

For requests classified as small_change:

planning (lightweight: single bead, no multi-model refinement)
  → present one-phase plan and wait for approval
  → validating (lightweight: single-story phase, abbreviated verification + bv check)
  → swarming (single worker)
  → executing
  → reviewing (lightweight but still required)
  → compounding (only if a lesson was learned)

Choose small_change when ALL of these are true:

• Change touches ≤3 files
• No new API surface or data model changes
• Risk is clearly LOW
• No gray areas about intent
• The phase can honestly be expressed as one story

standard_feature

Use this for the default Anionzo chain. This is the normal case for most feature work:

exploring → planning → validating → swarming → executing → reviewing → compounding

high_risk_feature

Use this when the work is cross-cutting, hard to reverse, or likely to fail if assumptions are wrong.

Additional expectations:

• more discovery depth during planning
• explicit second-opinion refinement during planning
• spike discipline for risky items during validating
• slower approval at GATE 3 before execution begins

---

Priority Rules

These override everything else:

1. P1 review findings always block. Never merge, never close epic, never proceed to compounding while P1 findings are open.
2. Context budget always applies. After each bead completion or major phase, if context >65% used: write .anionzo/HANDOFF.json and pause. Do not continue burning context.
3. CONTEXT.md is the source of truth. If implementation diverges from a locked decision in CONTEXT.md, stop and surface the conflict before proceeding.
4. GATE 3 is the most critical gate. Execution is irreversible. If there is any doubt about the current phase's soundness, do not approve. Loop back to validating.
5. Spike failures halt the pipeline. A failed spike means the approach is broken. Do not proceed to swarming; return to planning.
6. Never skip validating. Not for small features. Not for "obvious" plans. Skipping validating is the #1 cause of wasted execution work. (GSD: "Plans are not executed until they pass verification.")
7. critical-patterns.md is mandatory context. If it exists, read it before planning or executing anything. Teams report that ignoring past critical patterns is the #1 source of repeat failures.

---

Communication Contract

This is the default way Codex and GPT models should communicate anywhere inside the Anionzo workflow unless a narrower skill requires something stricter.

The default tone

• practical first, abstract second
• scenario-first, not jargon-first
• explain what happens in real life or in the real system before naming the technical property
• translate decision IDs, invariants, and architecture terms into plain language
• prefer "here is what the code does today" over "here is the category of bug"

What a good response sounds like

When presenting a plan, finding, blocker, or handoff, the model should usually answer in this order:

1. Plain-language summary — what is happening or what is proposed
2. Current behavior or current state — what the system does today
3. Why it matters — what requirement, decision, or goal this affects
4. Concrete scenario — one realistic example with values, timestamps, requests, user actions, or ordering
5. Next step — the smallest credible fix, revision, or decision needed

What to avoid

• terse shorthand like "violates D5", "non-monotonic", "race condition", "coverage gap", or "architecture concern" without immediate explanation
• summaries that assume the reader remembers the diff or the planning session
• abstract labels with no example of what would actually happen
• explanations that begin with terminology and only later reveal the user-visible problem

Translation rule

If you use technical language, immediately translate it.

Examples:

• Instead of: This write is non-monotonic. Say: An older update can overwrite a newer timestamp, so the system can think the user was last active earlier than they really were.

• Instead of: Violates D5. Say: Decision D5 says the fallback should use the most recent inbound user message time. Right now the code uses webhook ingest time instead, which can drift from the real message time.

Scope

Apply this tone to:

• planning phase and story explanations
• validating failures and approval summaries
• reviewing findings and user-facing summaries
• swarming blocker reports and handoffs

If a skill gives a structured format, keep the structure but make the content follow this tone.

---

Red Flags

Watch for these violations. Pause and surface them immediately when detected:

Skipping phases:

• Agent jumps from exploring → swarming (skipped planning + validating)
• Agent starts writing code before CONTEXT.md exists
• Agent skips validating because "the plan looks fine"

Context violations:

• Downstream agent ignores a locked decision in CONTEXT.md
• Bead description contradicts the approach in approach.md
• Implementation diverges from locked decisions without surfacing conflict

Execution violations:

• Files reserved but never released (Agent Mail reservation leak)
• Bead closed as "done" without the acceptance criteria actually verified
• Agent commits code without a bead ID in the commit message

Quality violations:

• P1 finding present but pipeline continues to merge
• br close called on a bead with placeholder/stub implementation
• Review skipped outside the approved lightweight small_change flow

State violations:

• Context >65% but no HANDOFF.json written
• Session resumed without reading HANDOFF.json
• state.json missing or stale after a phase transition
• STATE.md not updated after a phase transition

---

File Quick Reference

.anionzo/
  onboarding.json   ← Anionzo plugin onboarding status + managed asset versions
  state.json        ← Machine-readable routing snapshot used by agents and tools
  STATE.md          ← Current phase, focus, blockers (update at every phase transition)
  config.json       ← Feature toggles (absent=enabled)
  HANDOFF.json      ← Session resume data (write when pausing)

.codex/
  anionzo_status.mjs  ← Read-only scout command for onboarding, state, and handoff
  anionzo_state.mjs   ← Shared state helpers used by the scout command

history/<feature>/
  CONTEXT.md        ← Locked decisions from exploring (source of truth)
  discovery.md      ← Research findings from planning
  approach.md       ← Synthesis + risk map from planning
  phase-plan.md     ← Full feature broken into phases and stories before execution
  phase-<n>-contract.md ← Current-phase entry state, exit state, demo, unlocks, pivot signals
  phase-<n>-story-map.md ← Story sequence inside the current phase; maps stories to beads

history/learnings/
  critical-patterns.md      ← Promoted critical learnings (read always)
  YYYYMMDD-<slug>.md        ← Individual learning entries

.beads/             ← Bead files (managed by br)
.spikes/            ← Spike verification results
.worktrees/         ← Git worktrees for parallel execution

---

Chaining Contract

Each skill reads from upstream artifacts and writes for downstream:

Skill	Reads	Writes
exploring	(user conversation)	history/<feature>/CONTEXT.md
planning	CONTEXT.md, critical-patterns.md	discovery.md, approach.md, phase-plan.md, current-phase contract/story map, current-phase beads
validating	phase-plan.md, current-phase contract/story map, current-phase beads, approach.md, CONTEXT.md	validated current phase, .spikes/ results
swarming	validated beads, state.json, STATE.md	Agent Mail threads, HANDOFF.json, updated state.json, updated STATE.md
executing	bead file, Agent Mail, CONTEXT.md	implementation commits, br close
reviewing	diff, CONTEXT.md, approach.md, beads	P1/P2/P3 findings
compounding	review findings, full feature history	history/learnings/YYYYMMDD-<slug>.md, critical-patterns.md

Handoff phrase pattern: Every skill ends with an explicit handoff: "[Outcome]. Invoke [next-skill] skill."