Tool Lifecycle

From creation to retirement — every stage is explicit.

Every ANCC tool follows the same lifecycle. Each stage has a defined action, a validation gate, and a failure path. Nothing is implicit.

create → validate → publish → version → use → deprecate → revoke

Create

Action: Agent or human identifies a gap. Before creating, search for existing tools that cover the capability.

# Check if the capability already exists
ancc search "postgresql diagnostics"
# → pgpulse: high overlap — consider extending

# No match? Scaffold a new tool
ancc scaffold pg-bloat-checker --type diagnostic
cd pg-bloat-checker && go mod tidy

Gate: The extend-vs-new rubric decides whether to create or extend. A change belongs in the existing tool only if it strengthens the same job, uses the same trust boundary, the same input world, the same output contract, and does not weaken scope boundaries. Otherwise: new tool.

Failure path: If the rubric says extend, the agent abandons creation and files an improvement against the existing tool instead.

When the rubric is ambiguous. Cheap models running at scale hit this constantly — the rubric scores 2 or 3 out of 5, and the agent cannot break the tie. The escalation chain:

  1. Try harder locally. Refine the search query. Re-read the existing tool's SKILL.md and Handoffs section. Check if the gap is one command, not a whole tool.
  2. Conservative default. When still uncertain, default to extend — it is always safer to add a command to an existing tool than to create a new one. Scope pressure detection will catch over-extension later.
  3. Structured escalation. For genuinely ambiguous, high-impact decisions: submit the rubric scores, gap description, and existing SKILL.md to an adversarial reasoning service (e.g., POST /v1/consult) for a multi-perspective verdict. This is a court of appeal, not a default path — expensive, rare, reserved for real ties.
  4. Human escalation. If no reasoning service is available or the verdict is still split: create a work order describing the ambiguity and let a human decide.

The rule: repeated ambiguity on the same pattern means the rubric or search needs improving — file a work order to fix the decision infrastructure, not keep escalating the same question.

Validate

Action: Run ancc validate before the tool enters the ecosystem. This is not advisory — it is a gate.

ancc validate .
# 28 pass, 0 fail, 2 warn

# CI enforces on every push:
# .github/workflows/ancc.yml runs ancc validate automatically

Gate: 30 checks across structure, semantics, and ecosystem fitness. Zero fail required. Checks include:

Failure path: Tool does not pass validation → does not enter the ecosystem. Fix the failures, re-validate.

Publish

Action: Push to GitHub with the ancc topic. Add the ANCC badge to README. The tool is now usable by any ANCC-aware agent.

git init && git add -A && git commit -m "feat: initial release"
gh repo create yourorg/pg-bloat-checker --public --source=. --push
gh repo edit yourorg/pg-bloat-checker --add-topic ancc

Gate: CI runs ancc validate on push. The ANCC workflow must pass. Agents with access to the tool can now read its SKILL.md and use it.

Failure path: CI fails → push succeeds but the tool is flagged as non-compliant. Governance detects and creates a binding directive to fix.

Version

Action: Tag releases with semantic versioning. SKILL.md and JSON output schemas evolve with the tool.

Rules:

Failure path: Breaking change without version bump → downstream agents get unexpected output → ancc verify detects contract drift.

validate vs verify

ancc validate checks SKILL.md correctness — does the documentation meet all 30 convention checks? Run at authoring time and in CI. ancc verify checks runtime contract fidelity — does the tool's actual output match what SKILL.md declares? Run after releases and by governance to detect contract drift. Validate is "is the spec well-formed?" Verify is "does the tool match its spec?"

Use

Action: Agents read the tool's SKILL.md, run commands, parse JSON output, and hand off to the next tool in the chain.

# Agent reads SKILL.md → knows commands, flags, output schema
pg-bloat-checker check --format json | jq '.checks[] | select(.status == "fail")'

Gate: The tool's doctor command (if present) reports runtime readiness. An agent can check health before trusting output.

Failure path: Doctor reports degraded → agent distrusts affected fields (per declared failure modes) → falls back to safe behavior or hands off to a different tool.

Deprecate

Action: When a tool or command is no longer needed, mark it in the Deprecated section of SKILL.md. Set an expiry version.

## Deprecated

### pg-bloat-checker legacy-scan
Deprecated in v1.3.0. Use `check` instead. Will be removed in v2.0.0.

Gate: ancc validate detects deprecated commands past their expiry. Governance flags tools with persistent deprecation markers.

Failure path: Deprecated command still in use by downstream agents → handoff contract routes them to the replacement. Agents follow the contract, not the habit.

Revoke

Action: A tool that is abandoned, compromised, or superseded is archived. Not deleted — archived with a clear signal.

Gate: Governance staleness check detects tools with no commits, no releases, and no reported usage. Creates a binding directive: justify continued existence, transfer ownership, or archive.

Failure path: Stale tool persists → governance escalates → human decides.

The complete picture

┌─────────┐     ┌──────────┐     ┌─────────┐     ┌─────────┐
│ CREATE  │────▶│ VALIDATE │────▶│ PUBLISH │────▶│ VERSION │
│scaffold │     │30 checks │     │topic+CI │     │ semver  │
└─────────┘     └──────────┘     └─────────┘     └─────────┘
                     │                                 │
                     │ fail                             │
                     ▼                                 ▼
                ┌─────────┐                      ┌─────────┐
                │  FIX or │                      │   USE   │
                │ ABANDON │                      │ compose │
                └─────────┘                      └─────────┘
                                                       │
                                                       ▼
                                                 ┌───────────┐
                                          ┌─────▶│ DEPRECATE │
                                          │      └───────────┘
                                          │            │
                                    governance         ▼
                                     signal      ┌──────────┐
                                          └─────▶│  REVOKE  │
                                                 │ archive  │
                                                 └──────────┘

Every stage has an action, a gate, and a failure path. Nothing is left to convention-by-hope. The system enforces lifecycle discipline from first commit to final archive.