English · Português (pt-BR)

cstk

Autonomous software engineering with an audit trail. Specs in, verified
code out: persistent state, bounded decisions, execution in waves, measured
cost. Runs on Claude Code and on the Codex CLI.

                        ██   ██
                      ██   ██     ██████╗ ███████╗████████╗██╗  ██╗
   ▄██████▄   ▄████▄ ▄███████▄   ██╔════╝ ██╔════╝╚══██╔══╝██║ ██╔╝
  ██████████▄▄██████ ████  ███   ██║      ███████╗   ██║   █████╔╝
  ▀████████▀  ▀████▀ █████████   ██║      ╚════██║   ██║   ██╔═██╗
    ▀▀▀▀▀▀    ▄████▄  ▀▀▀▀ ▀▀▀   ╚██████╗ ███████║   ██║   ██║  ██╗
            ▄█▀▄█▀ ▀█▄            ╚═════╝ ╚══════╝   ╚═╝   ╚═╝  ╚═╝
          ▄█▀ ▄█▀    ▀█▄

Why the leaf-cutter ant? We asked Claude: if cstk had a definitive
O'Reilly guide, which animal would be on the cover? The answer, without
hesitation:

The leaf-cutter ant. The cover animal has to tell the product's story, and
the leaf-cutter tells every chapter: it doesn't eat the leaf it cuts — it
orchestrates. The heavy lifting is done by the colony, in parallel waves,
each worker carrying a piece that fits its own context. If one falls along
the way, another resumes exactly where it left off, because the pheromone
trail is the shared memory of the work — their knowledge.db, an auditable
trace any of them can consult before deciding the next step. And model
routing comes for free: worker caste for the volume, soldiers for the heavy
stuff, a queen that only decides. Autonomy without a black box, with
provenance recorded on the ground.

And in the colophon, that classic footnote about the animal: "the
leaf-cutter ant thrives in any POSIX environment and considers logs without
provenance a threat to its habitat."

That's why the ant lives in the cstk CLI header.

What ships in the cstk CLI: a Spec-Driven Development pipeline (briefing →
review-features) as skills you can also use one at a time; autonomous
orchestrators (/agente-00c, /feature-00c) that run that pipeline end to
end and pause only on real blockers; a persistent state runtime with
formal resume/abort; cross-feature memory; per-wave model routing;
enforced guard hooks; and a local metrics panel where every number is
measured, never estimated.

Who maintains it / who it's for. Maintained by a single person, optimized
first for the maintainer's workflow (Go microservices). Skills, hooks and
CLI are general-purpose. The autonomous orchestrator is in production use by
the maintainer (this repository's own features are built with it); its
interface may still change between major versions.

Current version: latest release
· history in CHANGELOG.md. Installation recommended via
the cstk CLI (see Installation).

An autonomous agente-00c run seen from the web panel: per-wave
timeline with real cost, decision scores and invoked skills — every number
measured locally, never fabricated. More shots in Screenshots.

Start here

Two tracks, depending on what you're looking for:

Track	For whom	Where to go
Basic	Wants day-to-day productivity — specify, review, fix, document with a few skills	This section + Global Skills
Advanced	Wants the autonomous orchestrator running the whole SDD pipeline on its own	Advanced track

Basic track in 3 steps

# 1. Install (once per machine)
curl -fsSL https://github.com/JotJunior/cstk/releases/latest/download/install.sh | sh

# 2. Open Claude Code in your project and invoke a skill via its trigger:
#    "especifica essa feature: ..."   → specify  (idea → spec)
#    "revisa a segurança desse código" → owasp-security
#    "corrige esse bug: ..."          → bugfix   (multi-layer investigation)
#    "me aconselhe sobre esse plano"  → advisor  (strategic critique)

# 3. Done. Skills are auto-invoked by context — you describe the
#    intent in natural language and the trigger fires the right skill.

You don't need the autonomous orchestrator to get started. It's the advanced
track — adopt it when you want the SDD pipeline to run end to end without you
driving each step.

After installing: turn on cost and token capture

Two environment variables — no API key, no Admin key, no organization;
works on subscription plans:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

With these, every orchestrator wave records its real consumption (cost and
tokens, separating main from subagent) in .waves[N].otel_usage, and the
panel shows per-wave spend. Without them everything is a no-op and the field
stays null — absent, never a fabricated zero. Put them in your
~/.zshrc/~/.bashrc so you don't lose waves to forgetfulness.

Nothing leaves the machine (exporter binds 127.0.0.1:9464) and identity
labels are stripped before touching disk.

Running more than one Claude Code process at a time? Only the first can
bind the fixed port — the others silently measure nothing (otel_usage
null on every wave). Use the per-process port launcher shown in
Real per-wave cost to give each process
its own exporter automatically.

Screenshots

Panel overview (cstk serve): plan quota, real cost, running executions, model mix.	Tasks of an execution: outcome, tests and lint per task, 100% pass rate.
cstk recall: full-text memory across every past execution, with provenance (project/feature/wave/date).	The review-features skill building a cross-feature portfolio report inside Claude Code.
cstk doctor: installed catalog audited against the manifest — zero drift.

Structure

├── plugins/                     # Catalog, packaged as installable Claude Code plugins
│   ├── cstk/                    # Default plugin (marketplace entry "cstk")
│   │   ├── commands/            # The 7 /agente-00c*, /feature-00c*, /roadmap-wave slash commands
│   │   ├── agents/              # Orchestrators, clarify asker/answerer, data-veracity
│   │   ├── hooks/hooks.json     # 2 enforced guard hooks (bash-guard, tool-call-tick)
│   │   ├── .mcp.json            # registers the cstk-state MCP server (auto-starts on the plugin path)
│   │   ├── mcp/state-server/    # MCP server source (Node/TS, stdio) — ships INSIDE the plugin
│   │   ├── evals/               # `claude plugin eval` suite (generated from the skills' triggers.jsonl)
│   │   └── skills/               # 23 global skills (each skill is a folder)
│   │       ├── advisor/
│   │       ├── agente-00c-runtime/ # internal POSIX runtime (not user-invocable)
│   │       ├── analyze/
│   │       ├── apply-insights/
│   │       ├── briefing/
│   │       ├── bugfix/
│   │       ├── checklist/
│   │       ├── clarify/
│   │       ├── constitution/
│   │       ├── converge/           # reconciles spec/plan/tasks vs actual code
│   │       ├── create-tasks/
│   │       ├── e2e-integration-flow/ # full-stack E2E integration tests (Playwright)
│   │       ├── execute-task/
│   │       ├── model-selector/     # model routing heuristic (suggester)
│   │       ├── owasp-security/
│   │       ├── plan/
│   │       ├── presentation/       # narrative project deck (offline HTML) from the SDD docs
│   │       ├── reconcile-docs/     # brings feature docs up to date with the current code (docs follow code)
│   │       ├── review-features/
│   │       ├── review-task/
│   │       ├── specify/
│   │       ├── validate-docs-rendered/
│   │       └── validate-documentation/
│   ├── cstk-language-go/        # Go-profile plugin (marketplace entry "cstk-language-go")
│   │   ├── hooks/                # Go-specific hooks
│   │   └── skills/               # Go — see docs/go-toolkit.md
│   └── cstk-jira/                # Jira Cloud integration plugin (marketplace entry "cstk-jira")
│       ├── hooks/                # jira-sync drain + destructive-op deny guard
│       ├── scripts/              # jira-io.sh (jq + HTTP client), jira-config.sh, jira-sync.sh, ...
│       └── skills/                # 3 skills — see docs/specs/cstk-jira/quickstart.md
│           ├── jira-setup/       # guided setup (site, project key, credential, mappings)
│           ├── jira-convert/     # feature -> Epic/Task/Sub-task in Jira
│           └── jira-sync/        # sync status, conflicts and orphan cards
├── .claude-plugin/marketplace.json  # Marketplace manifest (3 entries: cstk, cstk-language-go, cstk-jira)
├── cli/                          # cstk binary + POSIX libs (not shipped by the plugin — FR-006)
└── docs/                         # Topic-based documentation (see index below)

Installed via the classic cstk CLI, this same content lands in
~/.claude/skills/, ~/.claude/commands/ and ~/.claude/agents/
(flattened, no plugins/cstk/ prefix). Installed via the native
Claude Code plugin, it materializes under the harness's own
installPath (see Installation for both paths).

Anatomy of a skill

Each skill is a folder with a SKILL.md (entry point) and, as needed,
subfolders consulted on demand (progressive disclosure — the model
pays only for the context needed at invocation time):

skills/<name>/
├── SKILL.md             # When to invoke, high-level rules, gotchas
├── templates/           # Fill-in templates
├── examples/            # Concrete cases (good.md vs bad.md)
├── references/          # Supporting documentation
├── scripts/             # Deterministic POSIX scripts
└── config.json          # Per-project configuration (optional)

Not every skill uses all subfolders — simple skills are just a SKILL.md.

Global Skills

Skills in plugins/cstk/skills/, independent of language or framework.

SDD Pipeline (Spec-Driven Development)

Recommended sequence to take an idea from discovery to implementation.
Details, flow diagram and shortcuts in
docs/sdd-pipeline.md.

Skill	Trigger	Description
briefing	"briefing", "discovery", "novo projeto"	Structured discovery interview (vision, users, constraints, stack)
constitution	"constitution", "princípios do projeto"	Immutable governance principles that guide decisions
specify	"specify", "criar spec", "nova feature"	Natural description → SDD feature spec (stories, requirements, success criteria). Gate: every requirement needs >=1 scenario; optional Delta Requirements section (living specs)
clarify	"clarify", "resolver ambiguidades"	Resolves spec ambiguities via structured questions (max 5)
plan	"plan", "plano técnico"	Implementation plan: research, data model, contracts
checklist	"checklist", "quality gate"	"Unit Tests for English" — validates REQUIREMENT quality; gaps become tasks
create-tasks	"criar tarefas", "criar backlog"	Task backlog by phases with dependencies and criticality
execute-task	"executar tarefa", "execute task"	Executes a task following the mandatory 9-step workflow
converge	"converge", "o código bate com a spec?"	Reconciles spec/plan/tasks against the CURRENT code and appends gaps as a new task phase. Regular pipeline stage between execute-task and review-task in the orchestrators
review-task	"revisar tarefas", "status das tarefas"	Status report with progress and recommendations

analyze is not a numbered sequential step — it is a read-only lateral
cross-check (spec/plan/tasks/constitution), usable at any point from
create-tasks onward.

Complementary Skills

Skill	Trigger	Description
advisor	"me aconselhe", "analise estratégica"	Brutally honest advisor that dissects reasoning and generates action plans
analyze	"analyze", "analisar consistência"	Read-only cross-artifact consistency analysis
bugfix	"bugfix", "fix bug", "debug"	Structured multi-layer bug-fixing protocol
e2e-integration-flow	"e2e", "playwright", "validar fluxo completo"	Full-stack E2E integration tests (UI → API → database → queue → side effects)
apply-insights	"aplicar insights", "melhorar claude.md"	Applies proven usage insights to CLAUDE.md, hooks and workflows — see Usage insights
presentation	"apresentação do projeto", "deck executivo", "relatório humanizado"	Writes the project story as an offline HTML deck (slides, report, PDF) from briefing, constitution and every spec, one slide per spec; facts and metrics only from a deterministic inventory
reconcile-docs	"atualizar a documentação da feature", "a spec ficou desatualizada", "sincronizar docs com o código"	Reverse of converge: updates feature docs (spec, plan, data-model, contracts, quickstart) to match the current code, with inline markers and cited evidence; never changes code; supports --all and --dry-run
owasp-security	When reviewing security	Checklist-guided review (OWASP Top 10:2025, ASVS 5.0, LLM/Agentic, NIST, OAuth 2.1...). Does not replace audit/pentest
review-features	"status global", "comparar features"	Cross-feature report suggesting archive/abandon/prioritize; the archive action applies deltas to the living-specs corpus
validate-documentation	"validar documentação", "verificar UC"	Validates individual documents against structural standards
validate-docs-rendered	"validar renderização", "verificar diagramas"	Validates that the Markdown renders (Mermaid, links, frontmatter, tables)

Advanced track (autonomous orchestrator)

Maturity — in production use by the maintainer (this repository's own
features are built with it). No support guarantees for external adoption;
the interface may change between major versions.

/agente-00c drives the entire SDD pipeline over a target project, pausing
only on real blockers; /feature-00c does the same for ONE feature in an
existing project. Subsystems: per-wave model routing, atomic-commit mode
(automatic commits + push/PR at finalize), enforced guards (fail-closed hook),
parallel sessions in worktrees, roadmap mode (briefing → constitution →
docs/roadmap.md with a dependency DAG) that can end by offering a
parallel wave of independent features — each opened as a cstk session
worktree + named claude session (tmux pane when available), with the child
sessions notifying the coordinator via cross-session messaging so the next
wave is offered as soon as the frontier moves — and cross-feature knowledge
memory consulted before deciding.

Since v7.3.0 a finished feature is no longer a dead end:
/feature-00c "<increment>" --reopen=<short-name> preserves the previous
execution as an immutable round, records the increment as
## Delta Requirements in the existing spec, and appends a new task phase
instead of regenerating the backlog — with an advisory opinion (reopen vs new
feature) and a human block before anything touches disk.

Topic	Document
/agente-00c + /feature-00c orchestrators, model-routing, atomic-commit, guards	docs/agente-00c.md
Parallel sessions (cstk session)	docs/cstk-session.md
Roadmap mode + parallel wave of features (post-roadmap offer, notification, next wave)	docs/agente-00c.md
Knowledge memory (cstk recall)	docs/cstk-recall.md
Loose usage tracking (cstk usage)	docs/cstk-usage.md
Web metrics panel (cstk serve)	docs/cstk-serve.md

Usage insights

The apply-insights skill is prescriptive: it reads your playbook
(~/.claude/insights/usage-insights.md, per user — generate it via Claude
Code's native /insights) and applies it to the project. Distinct from the
native /insights, which is introspective (analyzes your sessions).

Installation

Via cstk CLI (recommended)

The toolkit is installed via cstk — a POSIX shell CLI that downloads,
validates (SHA-256), installs and updates skills without requiring a clone of
the repository.

Bootstrap one-liner (installs cstk into ~/.local/bin/):

curl -fsSL https://github.com/JotJunior/cstk/releases/latest/download/install.sh | sh

After that, typical commands:

cstk --version                       # confirms installation
cstk install                         # installs the 'sdd' profile into ~/.claude/skills/
cstk install --cli=codex             # installs Codex workflows, MCP and hooks
cstk install --profile all           # installs ALL 30 skills (includes language-go)
cstk install advisor bugfix          # cherry-pick by name
cstk update                          # applies new releases preserving local edits
cstk update --force                  # overwrites locally edited skills
cstk list                            # lists installed skills + status
cstk doctor                          # detects drift between manifest and disk
cstk self-update                     # updates the cstk binary itself + cli/lib

For Codex, cstk install --cli=codex installs six native workflows:
feature-00c, feature-00c-resume, feature-00c-abort, and the three
equivalent agente-00c workflows. It configures the shared knowledge database
and preserves Claude installations. Use --knowledge-db /path/knowledge.db
to select the shared index, or --dry-run to inspect the plan. After installing,
start a new Codex session and review the plugin hooks in /hooks.
See the Codex adapter for support and validation.
This command requires a CSTK release containing the adapter; from this
checkout, run sh cli/cstk install --cli=codex.

Claude install/update touch only the catalog (skills/commands/agents in
~/.claude/); the runtime (cli/lib/*.sh + binary) updates via
cstk self-update.

Available profiles:

Profile	Content	Typical use
sdd	17 skills: complete Spec-Driven Development pipeline (briefing → review-features) + internal runtime, model-selector and the orchestrators' 4 quality gates	Default global installation
complementary	12 independent skills (advisor, bugfix, e2e-integration-flow, etc.)	Complements the SDD pipeline
all	All 30 skills (sdd + complementary + language-go)	Full installation
language-go	Go-specific skills + hooks	Only in Go projects

Default profile when none is given: sdd.

Project scope (./.claude/skills/ in the CWD instead of ~/.claude/skills/):

# In a Go project: installs skills + hooks + settings.json merge
cd ~/projects/my-go-app
cstk install --scope project --profile language-go

# Cherry-pick in project scope
cstk install --scope project advisor owasp-security

# language-* hooks ARE installed only in --scope project
# (in --scope global, hooks are omitted with a warning in the summary — FR-009c)

Via Claude Code plugin (native, no binary)

Since v6.9.0 the catalog is also distributable as a native Claude Code
plugin — no cstk
binary, no clone, no curl bootstrap:

/plugin marketplace add JotJunior/cstk
/plugin install cstk@cstk
# optional, Go projects only:
/plugin install cstk-language-go@cstk
# optional, Jira Cloud integration:
/plugin install cstk-jira@cstk

Enable the plugin and open a new session in any project — skills, the 7
/agente-00c*//feature-00c*//roadmap-wave commands and the enforced guard hooks
(pretooluse-bash-guard, posttooluse-tool-call-tick) activate
automatically, with no
cstk hooks install step (confirmed empirically — see
docs/specs/_archived/2026-08-08-claude-plugin-packaging/spec.md
§Clarifications, assumption A1). posttooluse-loose-usage.sh (opt-in
consumption capture) is deliberately not part of the plugin's
hooks.json — it stays an explicit opt-in via cstk hooks install --with-loose-usage, and it also needs CSTK_OTEL_ENDPOINT in the claude
process environment or it captures nothing
(docs/cstk-usage.md).

Choosing between the two paths:

	Classic (cstk CLI)	Plugin (native)
Install step	bootstrap one-liner + cstk install	/plugin marketplace add + /plugin install
Provides the cstk binary (recall, usage, mcp, session, serve, self-update)	Yes	No — the plugin format does not install a persistent binary on PATH (FR-006); use the classic bootstrap for these
cstk-state MCP server (the 7 state tools)	Mirrored to ~/.claude/mcp/state-server by cstk install; registered per project with cstk mcp install	Ships inside the plugin and is registered by its own .mcp.json — auto-starts, no per-project step
Guard hooks activation	Requires cstk hooks install per project	Automatic on session start, zero per-project step
Integrity verification	SHA-256 of the tarball, fail-closed (serve-integrity), fixed trusted-host allowlist	Commit pin (gitCommitSha) recorded by the harness + its own "Will install" trust dialog
Update propagation	cstk update (explicit, per invocation)	Not automatic: claude plugin marketplace update then claude plugin update cstk --scope <scope>, plus a session restart — the plugin CLI itself prints Restart to apply changes.

Both paths are equally official (no third, ungoverned distribution
mechanism — see FR-017 in
docs/specs/current/guards-defense-in-depth.md)
and deliver the same auditable content with comparable protection, not
identical mechanisms — pick the plugin for the fastest zero-binary
onboarding of skills + guard hooks, the classic CLI when you need
recall/usage/mcp/session/serve, or both together: cstk doctor/cstk hooks install detect the plugin and automatically avoid
double-registering the guard hooks (plugin wins; cstk doctor reports
aligned/diverged/duplicated-hooks with an actionable fix for each).

Jira Cloud integration (cstk-jira)

The 3rd marketplace plugin, distributed only as a native Claude Code plugin
(/plugin install cstk-jira@cstk — no cstk install profile, since it has
no dependency on the classic binary). It converts a documented feature
(spec.md + tasks.md) into an Epic with Task/Sub-task children in Jira
Cloud, keeps a dedicated board per target project and syncs status
autonomously during agente-00c/feature-00c executions.

Skill	Trigger	Description
jira-setup	"jira-setup", "configurar jira"	Guided one-time setup: site, project key, credential (own terminal, never chat), issue-type and status-workflow mapping, filter + board
jira-convert	"jira-convert", "converter para jira"	Converts a feature's spec.md/tasks.md into Epic/Task/Sub-task, recording the local<->Jira mapping (jira-map.tsv); safe to re-run — only creates what is missing
jira-sync	"jira-sync", "status do jira"	Shows the autonomous sync queue, conflicts and orphan cards, and drives the operator through resolving each one

Two guard hooks ship with the plugin: posttooluse-jira-sync.sh (drains
the outbox of task/wave outcomes into Jira during autonomous executions)
and pretooluse-jira-deny-destructive.sh (blocks destructive Jira MCP
tool calls such as issue deletion — cards are never deleted, only
disconnected/re-linked; once the plugin is configured, it also denies
Jira project creation via MCP while an agente-00c/feature-00c
execution is active).

Round r02 additions (opt-in via ProjectConfig keys, all default to the
r01 behavior when unset):

• Milestone sync (milestone_mode, default auto): the Epic and its
  Tasks are tagged with a Fix Version resolved from the active round
  (<feature>-rNN) or, once there is no active round, from
  milestone_release or the top ## [X.Y.Z] heading of CHANGELOG.md
  (an unreleased [Unreleased] heading leaves the milestone unresolved
  until one of the two is set, or milestone_mode=off disables it).
• Phase labels (labels_enabled, default on): Tasks/Sub-tasks are
  tagged phase-<N> from the ### FASE N heading they belong to, kept in
  sync when a task moves to a different phase.
• Dependency links (links_enabled, default on): edges declared in
  the backlog's ## Matriz de Dependencias become Jira issue links between
  the anchor Tasks of each phase; the link type is confirmed once during
  setup (link_type_id) or resolved automatically when unambiguous.
• Project creation under a human gate (FR-024): when no Jira project
  exists yet, the jira-setup skill can offer to create one, but only
  ever with explicit operator confirmation — inside an autonomous
  execution it always defers to a human-answered gate, never creates one
  on its own.
• Shared config across git worktrees (FR-023): jira-config.sh resolve-path reads ProjectConfig from the current worktree, falling
  back read-only to the main worktree's config — so parallel roadmap
  executions in separate worktrees can share one Jira setup while each
  keeps its own local sync queue/lock.
• jira-sync status --feature F surfaces the resolved milestone name and
  link counts (links_unrepresentable=N, links_stale=N) alongside the
  existing outbox/conflict/orphan report.

Prerequisites: jq and a command-line HTTP client (confined to a
single script, jira-io.sh, under the same zero-dependency carve-out
documented for the rest of the toolkit). The Jira API token is generated
by the operator and stored outside the repository, at
${XDG_CONFIG_HOME:-$HOME/.config}/cstk-jira/credentials with 0600
permissions (0700 on the containing directory) — it is never typed in
the chat transcript. Details: docs/specs/cstk-jira/quickstart.md.

00c runtime hooks (cstk hooks)

The two 00c runtime hooks — pretooluse-bash-guard.sh (fail-closed Bash
guard) and posttooluse-tool-call-tick.sh (per-wave tool-call metric) — only
run in a target project once they are copied into
.claude/hooks/ and registered in .claude/settings.json.

cstk install --scope project agente-00c-runtime does that, but it also
copies the skill, 7 commands and 7 agents into the repo. When you only want
the hooks, use:

cd ~/projects/my-target-project
cstk hooks install                    # touches .claude/hooks/ + settings.json only
cstk hooks install --dry-run          # show the plan without writing
cstk hooks install --project-path ../other-project
cstk hooks install --remove-classic   # de-duplicate against the plugin, no prompt
cstk hooks install --local            # register in settings.local.json (third-party repos)
cstk hooks status                     # read-only: where is each hook registered?

Third-party repos (--local, issue #135): when the client's team
versions .claude/settings.json on purpose, a personal tool has no business
in it. --local writes the registration to .claude/settings.local.json
instead — Claude Code sums hooks across scopes, and the local file is
normally gitignored — so the hooks fire only for you and the team's file
stays byte-for-byte untouched. The scripts still land in .claude/hooks/;
keep them out of the client's git status without touching their
.gitignore:

printf '.claude/hooks/\n.claude/settings.local.json\n.claude/*.bak\n.claude/*.bak-pre-dedup\n' >> .git/info/exclude

The two .bak patterns cover the backups the command itself writes —
settings.json.bak / settings.local.json.bak when it merges the
registration, and settings.json.bak-pre-dedup when it removes a duplicate
classic block. Without them the backup shows up in the client's
git status and rides along in a distracted git add -A (issue #163).

Idempotent like the default flow. If the other file already registers
the 00c hooks (both would fire, double-counting every tool call) the
command warns and offers the same removal as the plugin dedup
(--remove-classic skips the prompt). cstk hooks status and
guard-hooks-status.sh check read both files, so tick-mode keeps
answering hook and the orchestrator does not tick by hand on top of an
active hook.

When the plugin already provides the hooks, cstk hooks install skips the
classic provisioning (plugin wins) and, if the project still carries a
classic registration in settings.json, both layers would fire. In that
case it asks whether to remove the classic block, deleting only the 00c
hook entries — third-party hooks and every other key in the file are
preserved — and writing a backup to settings.json.bak-pre-dedup. Use
--remove-classic to skip the prompt (scripts/CI). Without a TTY and
without the flag the block is kept, with a warning: settings.json
belongs to the operator and is never rewritten without explicit consent.

Without this step the Bash guard is inert and tool_calls/agent_usage
stay at zero for every wave. To check the current state without writing
anything:

guard-hooks-status.sh check --projeto-alvo-path .
# <hook>  present|missing  registered|unregistered  current|stale|unknown

Re-run cstk hooks install after every cstk upgrade that touches the hooks:
the copies under .claude/hooks/ are snapshots and nothing reconciles them
with the catalog. A stale copy is as harmful as a missing one — it runs
an older ruleset. That is a real regression, not a hypothetical: after the
state.json → state.db cutover, projects kept a tick hook that only knew
how to read state.json, so tool_calls was 0 for every wave while the
check still reported "3/3 hooks active". The fourth column exists to make
that visible, and tick-mode falls back to manual in exactly that pairing
(backend-blind copy + state.db) so the metric survives until you
re-provision.

Real per-wave cost (otel-usage.sh)

Claude Code's native OpenTelemetry counters are incremented on every API
request and carry a query_source label (main / subagent /
auxiliary). A snapshot at wave start and another at wave end gives the
exact consumption of that wave — including the orchestrator's own spend,
which the spawn hook can never capture (the orchestrator's spawn encloses
the wave, so its tool_result arrives after the wave is already closed).

Opt in with two environment variables — no API key, no Admin key, no
organization; works on subscription plans:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

state-ondas.sh start/end then populate .waves[N].otel_usage
automatically. Without the variables everything is a no-op and the field is
null — absent, never a fabricated zero.

Measured on a delegated task: main $0.156, subagent $0.141,
auxiliary $0.001 — the subagent was ~47% of the spend, exactly the slice
the panel used to show as —.

The exporter binds 127.0.0.1:9464; nothing leaves the machine. Identity
labels (user_email, user_id, user_account_*, organization_id) are
stripped at snapshot time and never reach disk. Override the endpoint with
CSTK_OTEL_ENDPOINT if you changed the exporter port.

Multiple Claude Code processes at once? Give each one its own port. Only
ONE process can bind the fixed port 9464 — the first one launched wins.
Every other process (another terminal tab, another project) fails the bind
silently: its metrics are exposed nowhere, the per-wave snapshots scrape the
winner's stale sessions, and the delta guard correctly discards the result —
so otel_usage comes out null for every wave of that execution, with the
panel showing no cost at all. Real case: a two-day-old claude -c from an
unrelated project held the port and an entire 16-wave run measured nothing.

The fix is a launcher function in your ~/.zshrc (or ~/.bashrc) that asks
the OS for a free port at every launch (binding port 0 lets the kernel pick)
and points the cstk scraper at it via CSTK_OTEL_ENDPOINT — hooks and runtime
scripts run inside the Claude process, so they inherit both variables.

Since v6.9.0 you rarely need to do this by hand: cstk install offers this
wrapper as an opt-in on first install (writes it to your shell rc between
# >>> cstk telemetry >>> markers, only with explicit consent — never in
non-interactive environments), and cstk help telemetry prints the canonical
ready-to-paste block if you declined or want to set it up later.

# One OTel exporter per claude process: OS picks a free port at each launch.
claude() {
  local _otel_port
  _otel_port=$(python3 -c 'import socket; s=socket.socket(); s.bind(("127.0.0.1",0)); print(s.getsockname()[1]); s.close()' 2>/dev/null)
  if [ -n "$_otel_port" ]; then
    OTEL_EXPORTER_PROMETHEUS_PORT=$_otel_port \
    CSTK_OTEL_ENDPOINT="http://127.0.0.1:${_otel_port}/metrics" \
    command claude "$@"
  else
    command claude "$@"   # no python3: fall back to the fixed default port
  fi
}

The wrapper is also a hard requirement for loose-usage capture
(cstk usage, issue #162), not just a multi-process convenience:
posttooluse-loose-usage.sh gates on CSTK_OTEL_ENDPOINT and exits 0
in silence without it. Unlike the per-wave path — which falls back to the
fixed default port — loose capture has no fallback, so without the
variable (or an equivalent manual export) it stays inert and cstk usage
answers nao medido. See
docs/cstk-usage.md.

Zero per-session configuration: each claude you type gets an isolated
exporter and an isolated measurement. As a bonus, the delta's
"exactly-one-session-grew" guard only ever sees that process's sessions, so
ambiguity discards (null from concurrent sessions) all but disappear.

The wrapper only covers claude TYPED in your shell. It is a shell
function, and exec never resolves one — so until v9.4.0 every session
started by cstk session start --claude, cstk 00c or the roadmap's
parallel wave ran with no telemetry at all, which is exactly what
issue #168 measured. Since v9.4.0 those three launchers set the variables
themselves (one drawn port per process), so they no longer depend on your
rc, your shell or tmux — and neither does the native-plugin install, which
provisions no wrapper. Turn that off with CSTK_TELEMETRY_AUTO=0; an
explicit CSTK_OTEL_ENDPOINT or CLAUDE_CODE_ENABLE_TELEMETRY already in
the environment also wins. Anything launched outside both paths (IDE,
desktop app) still uses the fixed default port.

Quick diagnosis when the panel shows no cost for any wave: check who owns the
port and whether its working directory is the project you're actually running:

lsof -nP -iTCP:9464 -sTCP:LISTEN     # who owns the exporter port?
lsof -p <PID> | grep cwd             # ...and from which project?

Or let the runtime decide: otel-usage.sh preflight answers "will THIS
session be measured?" deterministically — status=ok (exporter owned by an
ancestor of this process), port-conflict with the owner's PID and cwd
(exit 3), exporter-down (exit 4), disabled or unverified. The 00c
launcher commands run it in their pre-flight diagnostics and relay any
warning to the operator before wave 001.

Interactive mode (numbered selector in a TTY) and dry-run:

cstk install --interactive   # lists numbered profiles + skills; selection via toggle
cstk install --dry-run --profile all
cstk update --dry-run

Plan usage gauge (cstk statusline + cstk plan-usage)

Since v7.2.0 the toolkit can also capture the plan usage gauge you see in
/usage — no OAuth credential, no API key: Claude Code already sends
rate_limits.five_hour/seven_day in the statusline payload on every
render, so the capture hook just reads what is already passing by and
persists it locally in the plan_usage table of
~/.claude/cstk/knowledge.db.

cstk statusline install    # wires the capture hook into ~/.claude/settings.json
cstk statusline status     # is the capture active (and settings.json still valid)?
cstk plan-usage            # latest capture per scope (five_hour / seven_day)
cstk plan-usage history    # time series; reuses --scope/--limit/--since from cstk usage

Opt-in by construction — nothing is captured until you run statusline install — and 100% local. An existing custom statusline command is preserved
and chained as a mandatory stdout pass-through, never silently overwritten. A
scope without measurement prints nao medido (null with --json) — never
a fabricated zero.

Manual installation (deprecated, still supported)

Directly copying the directories still works (cp -r plugins/cstk/skills/ ~/.claude/skills/), but does not track versions or detect drift — see
CLAUDE.md §"Installed vs Source Drift". cstk solves
this via manifest + hash_dir.

Complete cstk documentation

• cli/README.md — technical overview, conventions, release process
• docs/specs/_archived/cstk-cli/ — spec, plan, contracts, quickstart

Installation profiles (summary)

Profile	Content	Typical use
sdd	17 skills: complete Spec-Driven Development pipeline (briefing → review-features) + internal runtime, model-selector and the orchestrators' 4 quality gates	Default global installation
complementary	12 independent skills (advisor, bugfix, e2e-integration-flow, etc.)	Complements the SDD pipeline
all	All 30 skills (sdd + complementary + language-go)	Full installation
language-go	Go-specific skills + hooks	Only in Go projects

Default profile when none is given: sdd. Details in cstk install --help.

Documentation by topic

Topic	Document
SDD Pipeline: full flow, when to use each skill, shortcuts, living specs	docs/sdd-pipeline.md
Autonomous orchestrator (agente-00c / feature-00c)	docs/agente-00c.md
Parallel sessions (cstk session)	docs/cstk-session.md
Roadmap mode + parallel wave of features (post-roadmap offer, notification, next wave)	docs/agente-00c.md
Knowledge memory (cstk recall)	docs/cstk-recall.md
Loose usage tracking (cstk usage)	docs/cstk-usage.md
Web panel (cstk serve)	docs/cstk-serve.md
Go skills and hooks	docs/go-toolkit.md
Jira Cloud integration (cstk-jira) skills, hooks and setup	docs/specs/cstk-jira/quickstart.md
Naming conventions and docs hierarchy	docs/conventions.md
Browsable manual (site)	jotjunior.github.io/cstk

Security

cstk ships hooks that intercept tool calls (including one that matches
all tools — a passive, silent, always-exit-0 local counter), a Bash
guard that is fail-closed only during autonomous 00c executions, and a
CLI that refuses unverified release downloads (sha256 + fixed host
allowlist). Nothing cstk records ever leaves your machine.

What each hook does, what the guard blocks, how release integrity works and
how to report a vulnerability: SECURITY.md.

Contributing

Contributions are welcome. The complete guide — the system's mental model,
development flow, versioning policy and the global toolkit scope principle
(skills published here must not name specific clients, companies or projects) —
is in CONTRIBUTING.md. Summary for adding a skill:

1. Follow the folder structure of an existing skill (see Anatomy of a skill)
2. Lean SKILL.md as the entry point; heavy content in subfolders
3. description as a trigger condition, not a summary
4. Gotchas documented — the most valuable content of a skill
5. Scripts in POSIX sh for deterministic operations; every new .sh requires tests/test_<name>.sh
6. Generalize: if it references something from a specific project, it belongs in <project>/.claude/skills/, not in this toolkit
7. Test with Claude Code before submitting

Versioning

This project follows Semantic Versioning and keeps a
CHANGELOG.md with the change history.

Credits & Attributions

Part of the SDD pipeline is adapted from the GitHub Spec Kit
(MIT) — in particular the step vocabulary and the constitution template. The
living-specs model with delta requirements was inspired by
OpenSpec. Other skills had conceptual
inspiration from obra/superpowers
and from Claude Code conventions. Public standards (OWASP, NIST, IETF, W3C,
MITRE) are cited as reference. Details and license notices in
THIRD-PARTY-NOTICES.md.

License

Distributed under the MIT license. See the LICENSE file for the
full text.