# https://github.com/AlexZio00/sovereign-skills Project Manual Generated at: 2026-06-27 08:41:37 UTC ## Table of Contents - [Sovereign Skills Overview & Architecture](#page-1) - [Setup & Initialization Skills](#page-2) - [Daily Workflow & Discipline Skills](#page-3) - [Quality, Review & Session Management Skills](#page-4) ## Sovereign Skills Overview & Architecture ### Related Pages Related topics: [Setup & Initialization Skills](#page-2), [Daily Workflow & Discipline Skills](#page-3), [Quality, Review & Session Management Skills](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md) - [scope/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/SKILL.md) - [setup/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/SKILL.md) - [project-init/skill.md](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/skill.md) - [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md) - [stepback/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/stepback/SKILL.md) - [code-autopsy/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/code-autopsy/SKILL.md) - [setup/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/agents/openai.yaml) - [scope/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/agents/openai.yaml) - [project-init/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/agents/openai.yaml) - [pre-push/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/pre-push/agents/openai.yaml) - [project-check/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/project-check/agents/openai.yaml) - [session-checkpoint/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/session-checkpoint/agents/openai.yaml)
# Sovereign Skills Overview & Architecture ## What is Sovereign Skills **sovereign-skills** is a Claude Code marketplace (a collection of installable prompt-packages called "skills") that ships twelve skills covering the entire Claude Code project lifecycle — from greenfield setup, through daily implementation workflow, to code review and session continuity. The current release is v6.2, which added `code-autopsy` (12-question quantified code review with severity scoring), `stepback` (one-shot perspective reset), upgraded all ten existing skills, and added Codex compatibility via `npx skills` Source: [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md). Each skill is **useful standalone** but the full sequence covers everything: `/project-init` and `/setup` for bootstrapping, `/session-start` and `/session-checkpoint` for continuity, `/scope`, `/freeze`, and `/goal-lock` for discipline during implementation, `/stepback` for mid-flight re-orientation, `/code-autopsy` and `/pre-push` for review, plus `/project-check` and `/adr` for architecture. Skills are invoked by typing their slash-command (e.g. `/goal-lock`) inside Claude Code, which then reads the skill's `SKILL.md` and follows its instructions Source: [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md). ## Architecture A skill is a directory with a fixed shape so any LLM (Claude Code, Codex, Cursor) can consume the same instructions. The diagram below shows the canonical layout and request flow: ```mermaid flowchart LR A[User types /trigger] --> B[Claude Code / Codex] B --> C[Read SKILL.md or skill.md] C --> D{Read YAML
frontmatter} D --> E[Follow Stage pipeline
PARSE → STEP-BACK → CHECK → OUTPUT] E --> F[Emit result file
BRIEF.md / FROZEN SCOPE / verdict] subgraph Skill["skill/ directory"] C D E F end H[agents/openai.yaml] -.meta.-> C I[.claude-plugin/plugin.json] -.metadata.-> B ``` Each skill directory contains: | File | Purpose | |------|---------| | `SKILL.md` (or `skill.md`) | Universal instruction body — read by every LLM | | `agents/openai.yaml` | Codex metadata declaring `name`, `description`, `instructions` | | `.claude-plugin/plugin.json` | Claude Code marketplace metadata | The `openai.yaml` wrapper is a thin pointer to the same `SKILL.md`. For example, the `goal-lock` skill declares: `name: goal-lock` / `description: ...` / `instructions: "../SKILL.md"` Source: [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md). Identical patterns appear in [setup/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/agents/openai.yaml), [scope/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/agents/openai.yaml), and [project-init/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/agents/openai.yaml). The `SKILL.md` body itself uses YAML frontmatter to declare `skill_type`, `tools` allowed (e.g. `Read, Write, Bash`), `triggers` (multi-language slash-commands), `user_invocable`, and a `Dominant Variable` that defines what failure looks like for that skill Source: [project-init/skill.md](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/skill.md) Source: [setup/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/SKILL.md). ## Skill Categories & Lifecycle The twelve skills fall into four functional categories and are designed to chain together across the project lifecycle: | Phase | Skill | Trigger example | What it emits | |-------|-------|----------------|---------------| | Setup (one-time) | `project-init` | `/project-init` | `CLAUDE.md`, `ROADMAP`, `.gitignore`, `.env.example` | | Setup (one-time) | `setup` | `/setup` | `rules/`, hooks, `memory/`, agent routing | | Daily workflow | `session-start` | `/session-start` | handoff load + ready signal | | Daily workflow | `scope` | `/scope` | `BRIEF.md` (Quick) or `spec.md` (Full) | | Daily workflow | `freeze` | `/freeze` | `FROZEN SCOPE` block | | Daily workflow | `goal-lock` | `/goal-lock` | GOAL + DONE EVIDENCE input sheet | | Daily workflow | `stepback` | `/stepback` | one-line reframing question | | Code review | `code-autopsy` | `/code-autopsy` | 4-axis score + SHIP/FIX/RISKY/BLOCK verdict | | Code review | `pre-push` | `/pre-push` | secrets scan + agent review summary | | Architecture | `adr` | `/adr` | architecture decision record | | Architecture | `project-check` | `/project-check` | 6-axis / 58-item audit | | Session mgmt | `session-checkpoint` | `/session-checkpoint` | handoff rewrite + memory save | Source: [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md). The recommended daily sequence is documented in `README.md` as: `/session-start` → `/scope` → `/freeze` → `/goal-lock` → `/stepback` (anytime) → `/code-autopsy` → `/pre-push` → `/session-checkpoint`. Each skill gates the next: `freeze` blocks code generation until scope is locked Source: [freeze/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/freeze/agents/openai.yaml), and `goal-lock` enforces a `PLAN → DO → VERIFY → FINALIZE → OUTPUT` loop Source: [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md). ## Internal Pipelines (selected) Several skills implement explicit internal stage pipelines. `stepback` runs `PARSE → STEP-BACK → CHECK → OUTPUT` and enforces a **10-line output cap** and **1-question limit** Source: [stepback/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/stepback/SKILL.md). `scope` offers Quick mode (IN/OUT + exit criteria → `BRIEF.md`) or Full mode (L0→L4 layered spec chain → `spec.md`) Source: [scope/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/SKILL.md). `code-autopsy` scores twelve dimensions on a weighted 4-axis formula — **Security × 0.35 + Stability × 0.30 + Robustness × 0.20 + Operability × 0.15** — and emits a `SHIP / FIX / RISKY / BLOCK` deployment verdict Source: [code-autopsy/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/code-autopsy/SKILL.md). `goal-lock` auto-detects verification recipes per stack (e.g. `pytest -q` for Python, `cargo test` for Rust) Source: [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md). ## Installation & Multi-Agent Support Three install paths are supported and documented in `README.md`: 1. **Claude Code marketplace** — register the repo as `sovereign-plugins` via *Settings → Plugins → Add Marketplace* (URL: `https://github.com/AlexZio00/sovereign-skills.git`), then browse and install. 2. **Claude Code manual** — copy skill folders into `~/.claude/skills/`. 3. **Codex / Cursor** — `npx skills add AlexZio00/sovereign-skills --skill goal-lock --agent codex -g -y` (or `--agent cursor` / `--agent claude-code`). All three paths consume the same `SKILL.md` body Source: [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md) Source: [pre-push/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/pre-push/agents/openai.yaml). ## Design Principles `README.md` states five governing principles: **interview over template** (skills ask questions and generate filled content), **verification over trust** (DONE EVIDENCE must be executed, not assumed — "it should pass" is not verification), **scope before code** (define IN/OUT/exit criteria before touching files), **honest reporting** (`WORKING / PARTIAL / BROKEN` labels with no silent brokenness), and **session continuity** (start with handoff, end with checkpoint). The `Dominant Variable` declared in each `SKILL.md` frontmatter operationalizes these principles — e.g. `setup` declares "초기화된 하네스가 즉시 동작하는가" (does the initialized harness work immediately), and `project-init` declares that interview answers must exactly match generated `CLAUDE.md` content Source: [setup/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/SKILL.md) Source: [project-init/skill.md](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/skill.md). ## See Also - [Code-Autopsy Skill (12Q Review)](code-autopsy.md) - [Goal-Lock Skill (PLAN→DO→VERIFY loop)](goal-lock.md) - [Scope & Freeze Skills (scope discipline)](scope-freeze.md) - [Setup & Project-Init Skills (harness bootstrap)](setup-init.md) - [Session Continuity (start + checkpoint)](session-continuity.md) --- ## Setup & Initialization Skills ### Related Pages Related topics: [Sovereign Skills Overview & Architecture](#page-1), [Daily Workflow & Discipline Skills](#page-3)
Related Source Files The following source files were used to generate this page: - [project-init/skill.md](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/skill.md) - [project-init/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/agents/openai.yaml) - [setup/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/SKILL.md) - [setup/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/agents/openai.yaml) - [scope/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/SKILL.md) - [scope/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/agents/openai.yaml) - [freeze/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/freeze/agents/openai.yaml) - [session-checkpoint/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/session-checkpoint/agents/openai.yaml) - [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md)
# Setup & Initialization Skills The sovereign-skills repository is a curated set of skills that codify a software development lifecycle for AI coding agents. The **Setup & Initialization** tier covers the skills that run *before* any code is written: they capture user intent, lock scope, install the AI harness, and prepare session memory. These skills are the entry points most users hit first, and the community release notes (v4.0 through v6.2) repeatedly emphasize them as the foundation of the rest of the lifecycle. ## Purpose and Scope Setup & Initialization skills sit at the top of the pipeline diagrammed in the [README](README.md). They answer four questions before implementation begins: 1. What is the project? (`project-init`) 2. Is the AI harness configured correctly? (`setup`) 3. What is in and out of scope? (`scope`, `freeze`) 4. Where is the prior session state? (`session-start`, `session-checkpoint`) The v4.0 release introduced `session-start`, `session-checkpoint`, and the scope-locking skills as part of the "10 Skills, 4 Categories" restructuring, signaling that initialization is treated as a first-class category, not a miscellaneous pre-step. The v5.0 release added `/freeze` specifically to "lock scope before implementation" — a recurring pain point in agent-driven development. ## Project Init — Interview-Based Scaffolding `project-init` is a conversational skill that walks the user through a one-question-at-a-time interview before generating any files. Source: [project-init/skill.md](project-init/skill.md). The skill exposes two phases: - **Phase 1 — Interview.** Seven questions cover description, language/runtime, data layer, interface, deployment, Hard Rules, and team/timeline. The skill explicitly avoids bundling questions, listing decision guides (e.g., "Python: data, ML, automation" vs. "TypeScript: web UI, API server") inline so the user can self-serve. Source: [project-init/skill.md:11-44](project-init/skill.md). - **Phase 2 — Stack summary.** Confirms a condensed decision block before any file is written. The skill states: "Confirm with user before Phase 3." Source: [project-init/skill.md:55-66](project-init/skill.md). - **Phase 3 — File generation.** Emits `CLAUDE.md`, `docs/DEVELOPMENT_ROADMAP.md`, a stack-appropriate `.gitignore`, and `.env.example`. Each template is parameterized from interview answers — for example, the `Quick Ref` entry command is auto-filled from Q2 (`Python→pytest python {main}.py`, `Go→go run cmd/{app}/main.go`). Source: [project-init/skill.md:75-110](project-init/skill.md). A `Phase 0: Context Check` runs first and short-circuits if `CLAUDE.md` already exists, offering update/rewrite/cancel options. This is the skill's primary The dominant variable is *"whether decisions from the interview are faithfully reflected in the generated files"* — a mismatch silently sends the project down the wrong path. Source: [project-init/skill.md:9-11](project-init/skill.md). ## Setup — Harness and Agent Team `setup` is the companion skill for the AI orchestration layer rather than the project itself. Where `project-init` scaffolds *what the project contains*, `setup` installs *the rules the agent will obey*. Source: [setup/SKILL.md](setup/SKILL.md). The skill generates seven artifacts on first run: | # | Artifact | Condition | |---|----------|-----------| | 1 | `~/.claude/rules/project rules` | Always | | 2 | `~/.claude/rules/agents.md` | Standard+ | | 3 | `~/.claude/rules/output-style.md` | — | | 4 | `~/.claude/rules/development-workflow.md` | Review gates | | 5 | `~/.claude/settings.json` | Merge hooks | | 6 | `memory/MEMORY.md` | — | | 7 | `memory/session-handoff-LATEST.md` | Step 6 | Source: [setup/SKILL.md:13-26](setup/SKILL.md). A key principle documented in the skill: *"domain presets provide pre-filled rules with real content, not empty skeletons. Every harness includes reject-by-default and violation testing."* Source: [setup/SKILL.md:18-20](setup/SKILL.md). The `project rules` file is generated with a `Truth & Clarity Discipline` section that forces claims to be tagged as Fact / Claim / Disclosure, a feature the README highlights as one of the project's design principles. Source: [setup/SKILL.md:60-80](setup/SKILL.md). ## Scope and Freeze — Locking Before Implementation Once a project exists and a harness is in place, the next failure mode is scope creep. Two skills address this: - **`/scope`** runs in Quick mode by default, producing a `BRIEF.md` with IN/OUT/exit criteria. Full mode (`/scope full`) generates a layered L0→L4 `spec.md`. The dominant variable is *"whether OUT items are explicitly written"* — IN-only briefs allow scope to expand during implementation. Source: [scope/SKILL.md:18-22](scope/SKILL.md). - **`/freeze`** is a hard lock. Per the v5.0 release notes, it "parses your input to classify files as editable, frozen, or read-only," emits a `FROZEN SCOPE` block, and stops — no code generation, no agents. Ambiguous input triggers one clarifying question; if still vague, the broader scope is frozen. Source: [freeze/agents/openai.yaml](freeze/agents/openai.yaml). The combination — soft scope with `/scope`, hard scope with `/freeze` — is the project's answer to the community-cited failure mode of agents drifting past their remit. ## Session Lifecycle Two skills bracket each working session: - **`session-start`** loads the handoff, reviews lessons, and emits a ready signal at session open. Source: [session-checkpoint/agents/openai.yaml](session-checkpoint/agents/openai.yaml) (paired agent descriptor). - **`session-checkpoint`** extracts entities, rewrites the handoff, saves to `memory/MEMORY.md`, and provides compaction guidance at session close. Source: [session-checkpoint/agents/openai.yaml](session-checkpoint/agents/openai.yaml). Both are part of the v4.0 "Session" category and are prerequisites for any multi-session work the agent will perform. ## Common Failure Modes The repository documents several ways these skills can fail, and the skills themselves are designed to guard against them: - **Interview answers not reflected in generated files** — the dominant variable of `project-init`. Source: [project-init/skill.md:9-11](project-init/skill.md). - **Harness installed but inactive** — the dominant variable of `setup`. Source: [setup/SKILL.md:14-16](setup/SKILL.md). - **IN-only briefs** — the dominant variable of `/scope`. Source: [scope/SKILL.md:18-22](scope/SKILL.md). - **Pre-existing `CLAUDE.md` clobbered** — guarded by `Phase 0` of `project-init`. Source: [project-init/skill.md:148-160](project-init/skill.md). ## See Also - [Goal-Lock & Verification Skills](#) — what runs *after* initialization, including `goal-lock` and `code-autopsy`. - [Pre-Push & Review Skills](#) — agent-driven review and resilience. - [Session & Memory Skills](#) — detailed coverage of `session-start` and `session-checkpoint`. --- ## Daily Workflow & Discipline Skills ### Related Pages Related topics: [Sovereign Skills Overview & Architecture](#page-1), [Setup & Initialization Skills](#page-2), [Quality, Review & Session Management Skills](#page-4)
Related Source Files The following source files were used to generate this page: - [scope/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/SKILL.md) - [scope/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/agents/openai.yaml) - [freeze/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/freeze/SKILL.md) - [freeze/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/freeze/agents/openai.yaml) - [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md) - [goal-lock/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/agents/openai.yaml) - [stepback/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/stepback/SKILL.md) - [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md)
# Daily Workflow & Discipline Skills ## Purpose and Scope The **Daily Workflow & Discipline Skills** are a cluster of four skills in the sovereign-skills v6.2 suite that govern *what an agent is allowed to do, when, and how* during a normal development session. Unlike `/setup` and `/project-init` (which bootstrap a project) or `/code-autopsy` (which reviews finished code), these four skills sit *between* those endpoints and enforce disciplined behavior during the messy middle: deciding what to build, locking the scope, executing with goal integrity, and stepping back when focus drifts. Source: [README.md:1-40]() The four skills in this cluster are: | Skill | Role in daily workflow | |-------|------------------------| | `/scope` | Define IN/OUT and exit criteria before implementation | | `/freeze` | Lock the file scope just before code generation | | `/goal-lock` | Enforce PLAN→DO→VERIFY→FINALIZE→OUTPUT loop | | `/stepback` | One-shot perspective reset when work drifts | Source: [README.md:20-30](), [scope/SKILL.md:1-10](), [freeze/SKILL.md:1-10](), [goal-lock/SKILL.md:1-10](), [stepback/SKILL.md:1-10]() ## Architecture and Execution Flow These skills are designed to be invoked in sequence during a typical feature implementation. Each skill has a single dominant variable — the property whose presence indicates the skill succeeded — and each produces a *concrete artifact* (a markdown file, a frozen block, a verification receipt) rather than open-ended advice. ```mermaid flowchart LR A[Feature Request] --> B["/scope
BRIEF.md or spec.md"] B --> C["/freeze
FROZEN SCOPE block"] C --> D["/goal-lock
PLAN→DO→VERIFY loop"] D --> E{Code complete?} E -- No / drifting --> F["/stepback
1 reframing question"] F --> D E -- Yes --> G[Commit / Push] D -. unhandled risk .-> B ``` Source: [scope/SKILL.md:1-15](), [freeze/SKILL.md:1-15](), [goal-lock/SKILL.md:1-20](), [stepback/SKILL.md:14-30]() ### `/scope` — Define what is in and what is out `/scope` answers the question *"what are we actually building?"* It has two modes: - **Quick mode (default)**: emits a `BRIEF.md` containing IN, OUT, and exit criteria. - **Full mode (`/scope full`)**: produces a layered `spec.md` from L0 intent down to L4 technical decisions. Its dominant variable is the explicit OUT list. According to the skill definition: *"Scope OUT 항목이 명시적으로 작성되었는가 — IN만 있으면 구현 중 범위가 늘어난다"* (Are OUT items explicitly written? If only IN exists, scope grows during implementation). Source: [scope/SKILL.md:1-15]() ### `/freeze` — Lock the file scope before code generation `/freeze` parses the user's input to classify every touched file as **editable**, **frozen**, or **read-only**, then emits a `FROZEN SCOPE` block and immediately stops. It does not generate code and does not spawn agents. Key behaviors: - Ambiguous scope → asks **one** clarifying question. - Still vague after clarification → freezes the **broader** scope (fail safe toward less damage). - The discard rule prevents use when the work is already complete or when scope is being redefined. Source: [freeze/SKILL.md:1-20]() ### `/goal-lock` — Enforce the PLAN→DO→VERIFY→FINALIZE→OUTPUT loop Introduced in v6.0, `/goal-lock` is the discipline engine that holds an agent to its declared goal. It detects **11 success-masquerading patterns** (test deletion, mock wrapping, threshold relaxation, etc.) and runs two modes: - **Quick mode**: 3 fields (GOAL + DONE EVIDENCE + SCOPE) for small changes. - **Full mode**: 7 fields (adds RISKS, CONSTRAINTS, NON-GOALS, AUDIENCE) for everything else. The skill mandates that **DONE EVIDENCE must actually be executed**, not assumed — the canonical anti-pattern is *"it should be fine"*, which is downgraded to `NOT RUN: [reason]`. A GroundEval mechanism verifies that verification tool calls really executed; any claim of "tests passed" without an executed command is rejected. Source: [goal-lock/SKILL.md:1-30]() ### `/stepback` — One-shot perspective reset Adapted from the DeepMind step-back pattern, `/stepback` is read-only with zero side effects. It scans recent context and outputs: 1. **1** abstract reframing question. 2. **3** quick checks (scope drift, side effects, better approach). All output is capped at **10 lines**; the skill returns immediately and never continues the task. Its invariants forbid dialogue, multiple questions, and follow-up actions — making it a *lens*, not a workflow. Source: [stepback/SKILL.md:1-25](), [stepback/SKILL.md:25-40]() ## Usage Patterns and Common Failure Modes ### Recommended Daily Sequence From the README quick-start guide, the recommended order during a feature implementation is: ``` /session-start → load handoff /scope → define IN/OUT/exit criteria /freeze → declare editable zone /goal-lock → lock the goal, enforce PLAN→DO→VERIFY /stepback → anytime when direction feels off /code-autopsy → after implementation /pre-push → before push /session-checkpoint → at session end ``` Source: [README.md:24-40]() ### Failure Modes the Skills Are Designed to Prevent | Failure mode | Skill that catches it | Mechanism | |---|---|---| | Scope creep mid-implementation | `/scope`, `/freeze` | Explicit OUT list + frozen file classification | | Agent "success" via deleting tests or relaxing thresholds | `/goal-lock` | 11 detected masquerading patterns | | Verification performed in imagination, not execution | `/goal-lock` | GroundEval requires actual tool-call output | | Persisting on the wrong problem for hours | `/stepback` | 10-line cap + immediate return | | File modifications beyond what was agreed | `/freeze` | `FROZEN SCOPE` block halts generation | Source: [freeze/SKILL.md:1-20](), [goal-lock/SKILL.md:1-30](), [stepback/SKILL.md:14-40]() ### Discard Rules Each skill carries an explicit `Discard if` clause to prevent misuse: - `/scope`: not for bug fixes, single-file changes, or brainstorming. - `/freeze`: not for work already complete or scope being redefined. - `/goal-lock`: not for trivial edits where the overhead exceeds the value. - `/stepback`: not for retrospective review or specific change-impact analysis. Source: [scope/SKILL.md:1-15](), [freeze/SKILL.md:1-20](), [goal-lock/SKILL.md:1-20](), [stepback/SKILL.md:1-20]() ## Configuration and Tool Surface Each skill declares its tool surface via frontmatter metadata. The discipline skills are intentionally *minimal* in their tool permissions — they read context, write one artifact, and return. | Skill | Skill type | Declared tools | |---|---|---| | `/scope` | workflow | Read, Write, Edit, Glob, Grep, Agent, Bash, AskUserQuestion | | `/freeze` | (per SKILL.md frontmatter) | (see source) | | `/goal-lock` | (per SKILL.md frontmatter) | (see source) | | `/stepback` | (per SKILL.md frontmatter) | Read-only, zero side effects | The trigger phrases are exposed as both `/command` form and natural-language keywords (e.g., "스펙 잡아줘", "범위 잡아줘", "zoom out", "blind spot") so the skills can fire either explicitly or via intent recognition. Source: [scope/SKILL.md:1-12](), [scope/agents/openai.yaml:1-3](), [freeze/agents/openai.yaml:1-3](), [goal-lock/agents/openai.yaml:1-3]() ## See Also - [Project Initialization & Setup](README.md) — bootstrap skills that run *before* the daily workflow. - [Code Review & Audit Skills](code-autopsy/SKILL.md) — review skills that run *after* implementation. - [Session Continuity Skills](session-start/SKILL.md) — memory/handoff skills that bracket the daily workflow. --- ## Quality, Review & Session Management Skills ### Related Pages Related topics: [Sovereign Skills Overview & Architecture](#page-1), [Daily Workflow & Discipline Skills](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md) - [code-autopsy/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/code-autopsy/SKILL.md) - [code-autopsy/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/code-autopsy/agents/openai.yaml) - [project-check/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/project-check/SKILL.md) - [project-check/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/project-check/agents/openai.yaml) - [collab-audit/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/collab-audit/SKILL.md) - [collab-audit/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/collab-audit/agents/openai.yaml) - [session-start/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/session-start/SKILL.md) - [session-start/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/session-start/agents/openai.yaml) - [session-checkpoint/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/session-checkpoint/SKILL.md) - [session-checkpoint/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/session-checkpoint/agents/openai.yaml) - [pre-push/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/pre-push/SKILL.md) - [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md)
# Quality, Review & Session Management Skills ## Overview The Quality, Review & Session Management tier of sovereign-skills covers three concerns that surround the coding core: scanning existing code for quality gaps, running quantified reviews before shipping, and preserving context across coding sessions. Together, these skills form the closing arc of the daily loop documented in [README.md](README.md): `/session-start` opens a session, work is reviewed with `/code-autopsy` or audited by `/project-check`, and `/session-checkpoint` plus `/pre-push` close it out. The v6.2 release also positioned `/code-autopsy` as a skill "useful standalone" — it works as a prompt in any LLM, not only inside Claude Code (Source: [README.md]()). This page covers the four review-focused skills (code-autopsy, project-check, collab-audit, pre-push), the two session lifecycle skills (session-start, session-checkpoint), and the discipline engine (goal-lock) that sits between them. ## Code Review Skills ### code-autopsy — Quantified 12-Question Review Introduced in v6.2, code-autopsy is a standalone prompt that applies a 12-question framework with weighted scoring. From [code-autopsy/SKILL.md](code-autopsy/SKILL.md), the four scoring axes are: | Axis | Weight | Focus | |------|--------|-------| | Security | 0.35 | Input validation, secrets, permissions, CVEs, deprecated deps, license | | Stability | 0.30 | Runtime panic, edge cases, race conditions, deadlocks, async/await | | Robustness | 0.20 | Error handling, retry/timeout, circuit breaker, graceful degradation | | Operability | 0.15 | Structured logging, trace IDs, monitoring hooks, sensitive data handling | The 12 questions (Q1–Q12) cover Design, Conciseness, Bugs, Functionality, Security, Duplication, Performance, Commonization, Dead Code, Test Quality, Error Resilience, and Observability. Each question is paired with explicit empirical rules where evidence exists — for example, "Nesting ≤3 (Johnson 2019, N=275, d=0.48)" is marked as supported, while "do-while avoidance (d=0.01)" is marked as a myth (Source: [code-autopsy/SKILL.md]()). Two rules are explicitly marked ⛔ myth, signalling that not all "best practices" are treated as equally valid. The skill outputs a Severity Anchor Table scored on Impact, Probability, Fix Cost, and Detectability, then collapses into one of four deployment verdicts: SHIP, FIX, RISKY, or BLOCK. Two meta-detection gates prevent gaming: - **CapCode Ceiling Metric** — scores that exceed a project's legitimate performance ceiling are flagged as "⚠️ SCORE EXCEEDS LEGITIMATE CEILING" and downgraded to FIX FIRST. - **CEF Fabrication Detection** — fabricated external failures (system crash, API timeout) are flagged when error handling references codes that do not exist in the backend schema. A CRITICAL Reachability Gate requires that any 🔴 CRITICAL finding be both reachable and triggered under realistic conditions before the label is kept (Source: [code-autopsy/SKILL.md]()). ### project-check — Existing Project Audit `/project-check` scans an existing codebase across four dimensions: Infrastructure, Security, Quality, and Harness. Its agent description in [project-check/agents/openai.yaml](project-check/agents/openai.yaml) states it performs "static and behavioral analysis" using a 6-axis, 58-item checklist, with gaps ordered by severity. Unlike code-autopsy, which reviews recent code in isolation, project-check looks at the project as a system. The two skills complement each other: project-check finds structural gaps in the harness, code-autopsy finds specific defects in the code. ### collab-audit — Behavioral Profile [README.md](README.md) describes `/collab-audit` as a "14-section AI collaboration audit" that "analyzes your actual work patterns (not surveys) to generate behavioral profile, blind spots, and growth direction." It is the only review skill that examines the developer's process rather than the code's content — the other reviews look outward at files; this one looks inward at habits. ## Session Lifecycle Skills ### session-start Per the v4.0 release notes, `/session-start` performs three actions at the opening of every session: it loads the previous handoff, reviews the lessons in memory, and emits a ready signal (Source: [README.md]()). The skill exists so context survives across session boundaries — without it, each new session starts cold and the lessons learned in previous sessions are lost. ### session-checkpoint `/session-checkpoint` is the closing counterpart. Its agent description in [session-checkpoint/agents/openai.yaml](session-checkpoint/agents/openai.yaml) lists four actions: "extract entities, rewrite handoff, save memory, and compaction guidance." It is what makes the next `/session-start` useful — the two skills form a pair where neither works well without the other. ## Discipline and the Pre-push Gate ### goal-lock `/goal-lock` enforces the PLAN → DO → VERIFY → FINALIZE → OUTPUT loop described in [goal-lock/SKILL.md](goal-lock/SKILL.md). Its input sheet is GOAL plus DONE EVIDENCE, and it explicitly detects "11 success masquerading patterns (test deletion, mock wrapping, threshold relaxation)" — the patterns where work appears done but verification has been quietly relaxed (Source: [README.md]()). Quick mode covers small changes with 3 fields; Full mode requires 7 fields and a Plan capped at 3 lines. The skill sits inside the daily loop rather than at its edges: it is invoked before each piece of work, not just at session boundaries. ### pre-push The v4.7 release notes describe `/pre-push` v3.2.0 as adding two resilience behaviors: agent failure recovery (retry once, then report `⚠️ SKIPPED (agent unavailable — {agent})`) and conflict resolution when review agents give opposing opinions. The SKIPPED marker ensures that a failed agent is never silently treated as PASS — a failure is surfaced, not hidden (Source: [README.md]()). ## Workflow Position ```mermaid flowchart LR A[session-start] --> B[scope + freeze] B --> C[goal-lock] C --> D[work] D --> E[stepback] E --> F[code-autopsy / project-check] F --> G[pre-push] G --> H[session-checkpoint] ``` The diagram above mirrors the lifecycle flow in [README.md](README.md): session-start opens the loop, goal-lock enforces discipline during work, code-autopsy or project-check reviews the result, pre-push gates shipping, and session-checkpoint closes the loop by writing the next handoff. The collab-audit skill sits outside this daily loop — it runs periodically to reflect on long-term patterns rather than on a specific change. ## See Also - Project Setup Skills — `/project-init` and `/setup` that create the harness these skills run against - Scope, Planning & Discipline Skills — `/scope`, `/freeze`, `/goal-lock` and `/stepback` - Daily Workflow Skills — the position of these skills within the broader daily loop --- --- ## Pitfall Log Project: AlexZio00/sovereign-skills Summary: Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification. ## 1. Identity risk - Identity risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `npx skills` - Evidence: identity.distribution | https://github.com/AlexZio00/sovereign-skills ## 2. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/AlexZio00/sovereign-skills ## 3. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/AlexZio00/sovereign-skills ## 4. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/AlexZio00/sovereign-skills ## 5. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/AlexZio00/sovereign-skills ## 6. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/AlexZio00/sovereign-skills ## 7. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/AlexZio00/sovereign-skills ## 8. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/AlexZio00/sovereign-skills