@alexandrealvaro/agentic 0.5.1-beta.1 → 0.7.0-beta.1

package/README.md

@@ -40,6 +40,7 @@ Two categories ([ADR-0007](doc/adr/0007-workflow-operational-skills.md)) and two
 | `agentic-design` | spec-driven | auto if frontend detected | Bootstrap `DESIGN.md` from existing tokens (Figma, tailwind.config, tokens.json, CSS custom props) | `/agentic-design` |
 | `agentic-subagent` | spec-driven | auto if installing for Claude Code | Drafts `.claude/agents/<name>.md` (Claude Code only — Codex has no subagent primitive) | `/agentic-subagent` |
 | `agentic-skill` | spec-driven | opt-in only | Drafts a new Claude Code or Codex skill at the appropriate path | `/agentic-skill` |
+| `agentic-hooks` | workflow-operational | opt-in only | Scaffolds deterministic quality gates per WORKFLOW §11 (pre-commit + pre-push); detects stack and recommends a runner (Husky / lefthook / pre-commit / native) | `/agentic-hooks` |
 
 A short TUI shows the detected mode, agent, and feature signals (frontend / `.claude/` / `.agents/` presence) and lets you toggle the conditional skills. Non-interactive flags: `--agent claude-code | codex | both`, `--yes` to skip confirmations — auto-checked conditionals (e.g., `agentic-design` if the project has React) install; `agentic-skill` stays opt-in. Re-running on an installed project is idempotent — unchanged files report `·`, divergent ones prompt to replace.
 
@@ -88,6 +89,38 @@ npm install -g @alexandrealvaro/agentic@beta
 agentic init
 ```
 
+## Recommended daily sequence
+
+The kit ships nine universal skills plus three conditional ones — twelve discrete capabilities. The sequence below is a happy path through them for the three flows that cover most daily work. Skip steps that don't apply; the kit never enforces order.
+
+**Greenfield project, first non-trivial feature:**
+
+1. `agentic init` — install skills.
+2. `/agentic-bootstrap` — produce `AGENTS.md` (operational guide).
+3. `/agentic-architecture` — produce `ARCHITECTURE.md` once load-bearing patterns emerge.
+4. `/agentic-spec` — feature-level spec at `doc/specs/NNNN-<slug>.md` (User Scenarios, Requirements, Success Criteria).
+5. `/agentic-adr` — only when the feature forces a binding architectural decision worth recording for posterity.
+6. `/agentic-task` — work-unit decomposition; reference the spec via `Spec ref`.
+7. `/agentic-ground` — four-source research before code (`agentic-philosophy` auto-loads in parallel).
+8. Implement.
+9. `/agentic-review main..HEAD` — fresh-context §10 review before merge.
+10. `/agentic-audit` — periodic drift check across operational docs and specs.
+
+**Brownfield project, quick fix:**
+
+1. `agentic update` (only if you want upstream kit changes).
+2. Fix. `agentic-philosophy` auto-loads if the change is non-trivial.
+3. `/agentic-review` only if the fix is non-trivial. Trivial diffs skip the review.
+4. Commit.
+
+**Brownfield project, research-only ("what's the best way to add X?"):**
+
+1. `/agentic-ground` — runs the four-source research pass and surfaces the happy path with citations.
+2. Decide whether the answer becomes a spec (`/agentic-spec`) or a one-off task (`/agentic-task`).
+3. Continue from step 6 of the greenfield flow.
+
+The kit's discipline scales with the project's maturity. A solo PoC may legitimately skip `/agentic-spec` and `/agentic-adr` (the WORKFLOW §1 prune principle applies — don't add an artifact that wouldn't change agent behavior). A team product running on this kit is expected to use the full sequence and additionally invoke `/agentic-hooks` once to scaffold the deterministic gates per WORKFLOW §11 (pre-commit lint / format / secret-scan; pre-push build / unit / integration). Project maturity profiles that automate the recommendation by stack are deferred — see the next planned release.
+
 ## Manual prompts
 
 If you prefer to skip the installer, the same artifacts can be generated by pasting prompts directly into your agent. Each prompt file has the literal text to copy, plus the matching template structure:

package/WORKFLOW.md

@@ -62,16 +62,18 @@ Comments are exceptions. They justify *why* a non-obvious choice was made — ne
 
 ### Documentation Discipline
 
-Eight rules apply to every document the agent or the human writes in the project. They are framed against the failure modes the kit has actually seen — bloated `AGENTS.md`, README pages that drift into changelogs, decision artifacts diluted by speculation.
+The agent's authoritative copy of the eight-rule documentation discipline lives in the `agentic-philosophy` skill (`Documentation Discipline` section). The rules are summarized below for reference; the skill carries the full text agents read at session time. ADR-0008 records the canonical decision and the reconciliations against ADR-0004 (file-based task tracking) and ADR-0005 (universal agent behavior as a skill).
 
-1. **Definitions and decisions only.** Documentation captures what is true now and the decisions that brought it there. Speculation, history, and unfounded plans are out. A deferred decision is in scope when it is *recorded* — an accepted ADR or a task file is fundamentação; "we might do X later" without a record is speculation and is cut.
-2. **No dates, version stamps, `DRAFT` markers, or changelogs in narrative documents.** Applies to `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, specs, and any prose page. **Decision-record artifacts are exempt** — ADRs under `doc/adr/` (Nygard `Status` lifecycle requires a date) and tasks under `doc/tasks/` (append-only `Notes` log is the auditability surface). Use git history for narrative-doc evolution; keep the dated lifecycle inside the artifacts that need it.
-3. **No emoji anywhere.** Not in docs, code, source comments, commit messages, PR bodies, or skill outputs. Severity tags use plain words (`Blocker / Concern / Note`); status uses words (`accepted / superseded`); structural cues use Markdown.
-4. **Business context first.** Every document opens with *why* — the problem, the constraint, the user — before *what* and *how*. The first paragraph answers "what would break if this document didn't exist".
-5. **One scope per document. No duplication.** If two documents would say the same thing, link instead of copying. The canonical location owns the content; everywhere else references it.
-6. **Code is the primary documentation of behavior.** Comments justify *why* a non-obvious choice was made — never restate *what* the line does. If the comment is needed to explain *what*, rename or refactor.
-7. **No commented-out code; no orphan `TODO` / `FIXME` in source.** Every deferred item references a tracked work item — a GitHub Issue, or a per-task file under `doc/tasks/NNNN-*.md` (the kit's file-based tracking surface). The trace must be addressable from the source line.
-8. **Tests are living documentation of behavior.** Test names and assertions should read as the spec they enforce. When the spec changes, the test changes; when the test changes, the spec it documents must already have changed.
+1. **Definitions and decisions only.** No speculation, history, or unfounded plans.
+2. **No dates, version stamps, `DRAFT` markers, or changelogs in narrative documents.** Decision-record artifacts under `doc/adr/`, `doc/tasks/`, `doc/specs/` are exempt — their lifecycle fields are the auditability primitive.
+3. **No emoji anywhere.**
+4. **Business context first.**
+5. **One scope per document. No duplication.**
+6. **Code is the primary documentation of behavior.**
+7. **No commented-out code; no orphan `TODO` / `FIXME` in source.** Every deferred item references a GitHub Issue or a `doc/tasks/NNNN-*.md` task.
+8. **Tests are living documentation of behavior.**
+
+The skill body explains the rationale per rule, lists the failure modes the rules counter (bloated `AGENTS.md`, README pages drifting into changelogs, decision artifacts diluted by speculation), and walks through the reconciliations. Generator skills (`agentic-bootstrap`, `agentic-architecture`, `agentic-spec`, `agentic-task`, `agentic-adr`, `agentic-design`) reject violations of these rules at write time; `agentic-audit` flags drift across narrative docs and decision-record artifacts on demand.
 
 ## 3. Format by Evidence
 
@@ -86,29 +88,17 @@ Use XML when the prompt mixes instructions, retrieved context, examples, user in
 
 No format is universally best. **An observation from my practice, not benchmarked:** I've seen consistent gains when shifting prompts to XML — most noticeably with autonomous agents, where the prompt has to land alone without conversational refinement. Direct interactive use (Claude Code, Codex) tolerates loose Markdown; unattended agents don't. Claude in particular seems to respond well to XML, which I attribute to its training, but I haven't benchmarked it. Treat this as a starting hypothesis worth testing on your own target model and task before standardizing.
 
-## 4. Find the Happy Path
-
-Before implementing, ask:
-
-> *"What is the canonical, idiomatic way to implement [X] in [stack]? Cite official docs. List common deviations and why people take them."*
-
-Then check continuously, especially mid-implementation:
-
-> *"We are at step Y. Are we still on the happy path? If we deviated, was it deliberate?"*
-
-Sometimes you can't follow the happy path — that's fine. But always know where it is and why you left it.
-
-The kit ships `agentic-ground` (workflow-operational skill) as the bound implementation of §4 + §5: it runs a four-source research pass (official docs, validated open-source examples, in-repo patterns, git history), synthesizes the happy path with citations, and gates any deviation behind an irrefutable justification before code is written.
+## 4–5. Research Before Implementation
 
-## 5. Ground in Real Patterns
+Combines Find the Happy Path (canonical / idiomatic baseline) and Ground in Real Patterns (anchoring in project-specific examples). The kit treats both as one indivisible flow via `agentic-ground`; two prose sections would frame one operation as two separate practices.
 
-Don't dump the codebase into context. Anchor the model in a specific, project-relevant example.
+Two sub-practices, joined into one indivisible pass.
 
-> *"Find an existing example of [similar feature]; use that exact structure."*
+**Find the happy path.** Before implementing, ask: *"What is the canonical, idiomatic way to implement [X] in [stack]? Cite official docs. List common deviations and why people take them."* Mid-implementation: *"Are we still on the happy path? If we deviated, was it deliberate?"* Sometimes you can't follow the happy path — that's fine. Always know where it is and why you left it.
 
-Cite specific files, not "the codebase." Use just-in-time retrieval: pass paths or IDs and let the agent fetch via tools when it needs to read them.
+**Ground in real patterns.** Don't dump the codebase into context. Anchor the model in a specific, project-relevant example: *"Find an existing example of [similar feature]; use that exact structure."* Cite specific files, not "the codebase." Use just-in-time retrieval — pass paths or IDs and let the agent fetch via tools.
 
-`agentic-ground` (see §4) is the workflow-operational skill that combines this with the other three research sources — official docs, validated OSS, and git history — into one indivisible pre-implementation pass.
+The kit ships `agentic-ground` as the workflow-operational implementation of both. It runs a four-source research pass — official docs, validated open-source examples, in-repo patterns, git history — joined by AND not OR, synthesizes the happy path with citations from each source, and gates any deviation behind an irrefutable justification before code is written. Splitting the two sub-practices into separate skills would force two invocations with overlapping research outputs and fragment the synthesis context (ADR-0010).
 
 ## 6. Explore → Plan → Implement → Commit
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.5.1-beta.1",
+  "version": "0.7.0-beta.1",
   "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -83,6 +83,13 @@ export const CONDITIONAL_SKILLS = [
     hintWhenAuto: 'opt-in',
     hintWhenManual: 'opt-in (rarely needed)',
   },
+  {
+    name: 'agentic-hooks',
+    autoIf: () => false,
+    agents: ['claude-code', 'codex'],
+    hintWhenAuto: 'opt-in',
+    hintWhenManual: 'WORKFLOW §11 hooks scaffolder (pre-commit, pre-push)',
+  },
 ];
 
 function resolveAgents(flagValue, detectedAgents) {
@@ -275,6 +282,7 @@ export async function initCommand(opts) {
         ? ['/agentic-subagent']
         : []),
       ...(optedSkills.includes('agentic-skill') ? ['/agentic-skill'] : []),
+      ...(optedSkills.includes('agentic-hooks') ? ['/agentic-hooks (WORKFLOW §11)'] : []),
     ].join(', ');
     p.outro(
       `Done. In ${agents

package/src/lib/rootdoc.js

@@ -29,6 +29,8 @@ export const SKILL_DESCRIPTIONS = {
   'agentic-design': 'Bootstrap `DESIGN.md` from existing tokens (frontend projects).',
   'agentic-subagent': 'Draft a new Claude Code subagent at `.claude/agents/<name>.md`.',
   'agentic-skill': 'Draft a new Claude Code or Codex skill at the appropriate path.',
+  'agentic-hooks':
+    'Scaffold deterministic quality gates per WORKFLOW §11 — pre-commit + pre-push, runner detected from stack signals.',
 };
 
 /**

package/src/skills/claude-code/agentic-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentic-audit
-description: Read-only drift audit — compare AGENTS.md, ARCHITECTURE.md, and ADR statuses against what the code actually does. Outputs a drift list, never writes files. Use when the user wants to audit, review for drift, sanity-check, or report inconsistencies between the repo's docs and its code.
+description: Read-only drift audit — compare AGENTS.md, ARCHITECTURE.md, ADR statuses, feature specs in doc/specs/, and documentation discipline against what the code actually does. Outputs a drift list, never writes files. Use when the user wants to audit, review for drift, sanity-check, or report inconsistencies between the repo's docs and its code.
 allowed-tools: Read, Glob, Grep, Bash
 ---
 
@@ -10,7 +10,7 @@ Read-only. Produces a drift list comparing the repo's operational docs against w
 
 ## Step 1 — Decide what to audit
 
-If the user names an artifact (`AGENTS.md`, `ARCHITECTURE.md`, ADRs), audit only that. Otherwise audit all three categories below.
+If the user names an artifact (`AGENTS.md`, `ARCHITECTURE.md`, ADRs, specs), audit only that. Otherwise audit all categories below.
 
 ## Step 2 — Run checks
 
@@ -34,6 +34,16 @@ If the user names an artifact (`AGENTS.md`, `ARCHITECTURE.md`, ADRs), audit only
 * Status field — every ADR has one of `proposed | accepted | deprecated | superseded by ADR-NNNN`.
 * Superseded chains — every "superseded by ADR-NNNN" target exists.
 
+### Spec drift (if `doc/specs/` exists)
+
+Structural integrity only — does **not** deep-audit spec text against shipped code (deferred per [ADR-0011](../../doc/adr/0011-agentic-spec-skill.md) Consequences).
+
+* Numbering — gaps or duplicates in `doc/specs/NNNN-*.md`?
+* Status field — every spec has one of `draft | accepted | shipped | superseded by SPEC-NNNN`.
+* Superseded chains — every "superseded by SPEC-NNNN" target exists.
+* Reciprocity — every task under `doc/tasks/NNNN-*.md` whose `Spec ref` field is non-empty points to a spec that exists. And every spec with `Status: accepted` or `shipped` has at least one entry in its `Related → Tasks` list (an accepted spec with no implementing task is a smell).
+* Success Criteria coverage — when every task that references a spec is `done`, the spec's Success Criteria checkboxes should all be checked. A spec with all tasks `done` but unchecked Success Criteria boxes is drift between work-unit completion and feature-level claim.
+
 ### Documentation discipline drift (`WORKFLOW.md` §2 / ADR-0008)
 
 Audit narrative documents — `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, any prose page under `doc/` that is not a decision-record artifact under `doc/adr/` or `doc/tasks/`:

package/src/skills/claude-code/agentic-hooks/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: agentic-hooks
+description: Scaffold deterministic quality gates per WORKFLOW.md §11 — pre-commit (lint, format, secret-scan), pre-push (build, unit, integration). Detects the project's stack and recommends a hook runner (Husky / lefthook / pre-commit / native), scaffolds the runner config, and updates AGENTS.md Quality Gates. Use when the user wants to wire hooks, configure pre-commit / pre-push, set up quality gates, prevent --no-verify bypass, or close the WORKFLOW §11 advisory-vs-deterministic gap. Opt-in skill; not auto-installed in the universal set.
+allowed-tools: Read, Write, Glob, Bash
+---
+
+# /agentic-hooks
+
+Scaffolds the deterministic gates `WORKFLOW.md` §11 names. The skill writes config files for a hook runner and updates `AGENTS.md` Quality Gates; it does not execute install scripts. The user is responsible for the runner's one-time bootstrap (e.g., `npx husky init`, `lefthook install`, `pre-commit install`) — the skill says exactly which command to run.
+
+## Step 0 — Confirm the gates the user wants
+
+`WORKFLOW.md` §11 names two tiers:
+
+* **Pre-commit (fast):** lint, format, secret-scan. Runs on every commit. Slow pre-commits push devs to `--no-verify`; keep it under ~5s.
+* **Pre-push (thorough):** build, unit tests, integration tests. Runs on every push. Acceptable to be slow; the cost is paid less often than commit.
+
+Confirm both tiers are in scope for this project. If the user wants only one tier, scaffold only that tier — do not add gates the user did not ask for.
+
+Visual / E2E for UI projects (Cypress, Playwright, Claude in Chrome) are mentioned by §11 but live in CI, not pre-push. Out of scope for this skill.
+
+## Step 1 — Detect the runner
+
+Read the repo signals in this order:
+
+1. **Existing runner.** `.husky/` → Husky present. `lefthook.yml` or `.lefthook.yml` → lefthook present. `.pre-commit-config.yaml` → pre-commit present. `.git/hooks/` with non-sample scripts → native hooks present.
+2. **Stack signals (if no runner present).** `package.json` → Node-rooted; recommend Husky (most common in Node ecosystem) or lefthook (cross-language fit). `pyproject.toml` → Python-rooted; recommend pre-commit. `go.mod` → Go-rooted; recommend lefthook. `Cargo.toml` → Rust-rooted; recommend lefthook. Multiple stacks → recommend lefthook (cross-language by default).
+3. **No signals.** Recommend native `.git/hooks/` only as fallback. Warn the user that native hooks are not portable across clones (every contributor has to run a setup script).
+
+If multiple runners are present, surface the conflict and ask the user before scaffolding. Never silently pick.
+
+## Step 2 — Recommend the per-stack commands
+
+For the chosen runner, propose the per-tier command set:
+
+* **Node (`package.json` present):** lint = `npm run lint` (fall back to `npx eslint .` if no `lint` script); format check = `npm run format:check` (fall back to `npx prettier --check .`); secret-scan = `gitleaks detect --no-banner` (cite the install instruction); build = `npm run build` (skip if no script); test = `npm test`.
+* **Python (`pyproject.toml` present):** lint = `ruff check .`; format check = `ruff format --check .` or `black --check .`; secret-scan = `gitleaks detect --no-banner`; test = `pytest -q`.
+* **Go (`go.mod` present):** lint = `golangci-lint run`; format check = `gofmt -d .`; secret-scan = `gitleaks detect --no-banner`; build = `go build ./...`; test = `go test ./...`.
+* **Rust (`Cargo.toml` present):** lint = `cargo clippy -- -D warnings`; format check = `cargo fmt --check`; secret-scan = `gitleaks detect --no-banner`; build = `cargo build`; test = `cargo test`.
+* **Mixed / other:** ask the user for the per-tier command list. Do not invent.
+
+Offer to swap any default. Confirm before writing.
+
+## Step 3 — Scaffold the runner config
+
+Write the runner-specific config file. Below are the canonical shapes; adapt to the user's tier choices.
+
+**Husky** — `.husky/pre-commit` and `.husky/pre-push` (shell scripts). Plus a `prepare` script in `package.json` (`"prepare": "husky"`). User runs `npm install` once to bootstrap.
+
+**lefthook** — `lefthook.yml` at the repo root with `pre-commit` and `pre-push` commands keyed by stage. User runs `lefthook install` once.
+
+**pre-commit (pre-commit.com)** — `.pre-commit-config.yaml` referencing the canonical hooks for the stack (e.g., `pre-commit/mirrors-eslint`, `psf/black`, `astral-sh/ruff-pre-commit`). User runs `pre-commit install` and `pre-commit install --hook-type pre-push`.
+
+**Native `.git/hooks/`** — `.git/hooks/pre-commit` and `.git/hooks/pre-push` plus a `setup-hooks.sh` script the user runs after every clone (since `.git/` is not committed). Document the setup-script invocation in `AGENTS.md`.
+
+## Step 4 — Update `AGENTS.md` Quality Gates section
+
+Append (or refresh, if a Quality Gates section already exists) the following content:
+
+```
+## Quality Gates
+
+Deterministic enforcement — agent cannot skip.
+
+- Pre-commit hook (fast): <stack-specific lint, format, secret-scan commands>
+- Pre-push hook (thorough): <stack-specific build, unit, integration commands>
+- Hook runner: <Husky | lefthook | pre-commit | native>; config at <path>
+- Bootstrap: <one-line setup command>
+- CI blocks on: <list — skip if CI not yet wired>
+- Never bypass: no `--no-verify`, no skipped hooks, no deleted failing tests. WORKFLOW §11 is binding.
+```
+
+Honor the existing managed-skills / managed-quality-gates markers if `agentic-bootstrap` already wrote a Quality Gates section. The skill refreshes the section in place; user content outside the markers is preserved.
+
+## Step 5 — Tell the user what to run
+
+After writing the config, output exactly the bootstrap command the user must run (e.g., `npm install` for Husky, `lefthook install` for lefthook, `pre-commit install` for pre-commit). The skill does not execute the bootstrap — that is the user's call.
+
+If the user is wiring CI alongside hooks (GitHub Actions / GitLab CI / Circle), point them at the existing `.github/workflows/`, `.gitlab-ci.yml`, or `.circleci/` directory. CI scaffolding is a separate skill's responsibility (deferred — not this one).
+
+## Output contract
+
+Filesystem changes:
+
+- The runner's config file (e.g., `.husky/pre-commit`, `lefthook.yml`, `.pre-commit-config.yaml`).
+- An updated `AGENTS.md` Quality Gates section (or appended if absent), naming the runner, the gates wired, the bootstrap command, and the no-bypass policy.
+- For the native-hooks fallback only: a `setup-hooks.sh` script the user runs after every clone.
+
+The skill does not execute the runner's install command. The skill does not write CI config. The skill does not configure agent-side hooks (`.claude/settings.json` `Stop` / `PreToolUse` / `PostToolUse`) — that is a different surface; future ADR may cover it.
+
+A narrative document, so the documentation discipline rules apply at write time:
+
+- No emoji anywhere in the scaffolded config or in the AGENTS.md update.
+- No version stamps or DRAFT markers.
+- The Quality Gates section opens with the operational rule (gates are deterministic) before listing the gates themselves.
+- One scope: Quality Gates. Do not duplicate ARCHITECTURE.md or ADR rationale here.
+- No commented-out scripts. No orphan TODO / FIXME — every deferred command references a tracked task or GitHub Issue.

package/src/skills/claude-code/agentic-philosophy/SKILL.md

@@ -20,12 +20,9 @@ Before implementing:
 
 ## Ground Before Coding
 
-**Anchor in real patterns. Research the canonical path.**
+**Anchor in real patterns before writing code.**
 
-- Find the canonical/idiomatic way to do it. Note where you deviate and why.
-- Find an existing example in the codebase; reuse its structure.
-- Cite specific files, not "the codebase". Fetch via tools — don't dump code into context.
-- For non-trivial changes, explore (read-only) → plan → implement → commit. Skip for diffs you can describe in one sentence.
+For non-trivial changes, invoke `/agentic-ground` — the workflow-operational skill that runs the four-source research pass (official docs, validated open-source examples, in-repo patterns, git history) and synthesizes a happy path with citations. The skill carries the prescriptive deviation gate; this section carries the posture only. Skip for diffs you can describe in one sentence.
 
 ## Simplicity First
 

package/src/skills/codex/agentic-audit/SKILL.md

@@ -29,6 +29,13 @@ ADR drift (if `doc/adr/` exists):
 - Status field — every ADR has one of `proposed | accepted | deprecated | superseded by ADR-NNNN`.
 - Superseded chains — every "superseded by ADR-NNNN" target exists.
 
+Spec drift (if `doc/specs/` exists; structural integrity only — does NOT deep-audit spec text against code, deferred per ADR-0011):
+- Numbering — gaps or duplicates in `doc/specs/NNNN-*.md`?
+- Status field — every spec has one of `draft | accepted | shipped | superseded by SPEC-NNNN`.
+- Superseded chains — every "superseded by SPEC-NNNN" target exists.
+- Reciprocity — every task with non-empty `Spec ref` points to a spec that exists; every accepted/shipped spec has at least one entry in its Related → Tasks list.
+- Success Criteria coverage — when every task referencing a spec is done, the spec's Success Criteria checkboxes should all be checked.
+
 Documentation discipline drift (`WORKFLOW.md` §2 / ADR-0008). Audit narrative documents — `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, any prose page under `doc/` that is not a decision-record artifact under `doc/adr/` or `doc/tasks/`:
 - Emoji — any present? Rule 3 forbids emoji anywhere (docs, code, comments, commits, skill outputs).
 - Dates / version stamps / `DRAFT` markers / changelog blocks in narrative documents — Rule 2 forbids these. Decision-record artifacts under `doc/adr/` and `doc/tasks/` are exempt.

package/src/skills/codex/agentic-hooks/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: agentic-hooks
+description: Scaffold deterministic quality gates per WORKFLOW.md §11 — pre-commit (lint, format, secret-scan), pre-push (build, unit, integration). Detects the project's stack and recommends a hook runner (Husky / lefthook / pre-commit / native), scaffolds the runner config, and updates AGENTS.md Quality Gates. Use when the user wants to wire hooks, configure pre-commit / pre-push, set up quality gates, prevent --no-verify bypass, or close the WORKFLOW §11 advisory-vs-deterministic gap. Opt-in skill; not auto-installed.
+---
+
+<background_information>
+Scaffolds the deterministic gates `WORKFLOW.md` §11 names. The skill writes config files for a hook runner and updates `AGENTS.md` Quality Gates; it does not execute install scripts. The user runs the runner's one-time bootstrap (`npx husky init`, `lefthook install`, `pre-commit install`) — the skill names the exact command.
+
+Codex auto-trigger on description keywords is less mature than Claude Code's. If auto-invocation does not fire when the user asks about hooks, pre-commit, or quality gates, invoke the skill manually.
+</background_information>
+
+<instructions>
+Step 0 — confirm the gates the user wants. WORKFLOW §11 names two tiers:
+- Pre-commit (fast): lint, format, secret-scan. Runs on every commit. Keep under ~5s; slow pre-commits push devs to `--no-verify`.
+- Pre-push (thorough): build, unit tests, integration tests. Runs on every push. Acceptable to be slow.
+
+Confirm both tiers are in scope. If the user wants only one, scaffold only that tier.
+
+Visual / E2E for UI projects (Cypress, Playwright) live in CI, not pre-push. Out of scope.
+
+Step 1 — detect the runner. Read repo signals in this order:
+1. Existing runner. `.husky/` → Husky. `lefthook.yml` or `.lefthook.yml` → lefthook. `.pre-commit-config.yaml` → pre-commit. `.git/hooks/` with non-sample scripts → native hooks.
+2. Stack signals (if no runner present). `package.json` → recommend Husky or lefthook. `pyproject.toml` → recommend pre-commit. `go.mod` → recommend lefthook. `Cargo.toml` → recommend lefthook. Multiple stacks → recommend lefthook (cross-language by default).
+3. No signals. Recommend native `.git/hooks/` only as fallback. Warn the user that native hooks are not portable across clones.
+
+If multiple runners are present, surface the conflict and ask the user before scaffolding. Never silently pick.
+
+Step 2 — recommend the per-stack commands:
+- Node: lint = `npm run lint` or `npx eslint .`; format check = `npm run format:check` or `npx prettier --check .`; secret-scan = `gitleaks detect --no-banner`; build = `npm run build` (skip if no script); test = `npm test`.
+- Python: lint = `ruff check .`; format check = `ruff format --check .` or `black --check .`; secret-scan = `gitleaks detect --no-banner`; test = `pytest -q`.
+- Go: lint = `golangci-lint run`; format check = `gofmt -d .`; secret-scan = `gitleaks detect --no-banner`; build = `go build ./...`; test = `go test ./...`.
+- Rust: lint = `cargo clippy -- -D warnings`; format check = `cargo fmt --check`; secret-scan = `gitleaks detect --no-banner`; build = `cargo build`; test = `cargo test`.
+- Mixed / other: ask for the per-tier command list. Do not invent.
+
+Offer to swap any default. Confirm before writing.
+
+Step 3 — scaffold the runner config. Write the runner-specific config file:
+- Husky: `.husky/pre-commit` and `.husky/pre-push` (shell scripts) + `"prepare": "husky"` in `package.json`. Bootstrap: `npm install`.
+- lefthook: `lefthook.yml` at the repo root with `pre-commit` and `pre-push` commands keyed by stage. Bootstrap: `lefthook install`.
+- pre-commit: `.pre-commit-config.yaml` with stack-specific hook references. Bootstrap: `pre-commit install` and `pre-commit install --hook-type pre-push`.
+- Native: `.git/hooks/pre-commit` and `.git/hooks/pre-push` + a `setup-hooks.sh` script the user runs after every clone (since `.git/` is not committed).
+
+Step 4 — update `AGENTS.md` Quality Gates. Append or refresh the section with: pre-commit gate list, pre-push gate list, runner name + config path, bootstrap command, CI status if known, no-bypass policy. Honor existing managed markers if `agentic-bootstrap` already wrote Quality Gates.
+
+Step 5 — tell the user the bootstrap command. Output the exact one-line command the user runs. The skill does not execute it.
+</instructions>
+
+<output_contract>
+Filesystem changes:
+- The runner's config file (`.husky/pre-commit`, `lefthook.yml`, `.pre-commit-config.yaml`, or `.git/hooks/`).
+- An updated `AGENTS.md` Quality Gates section.
+- For native-hooks fallback: a `setup-hooks.sh` script.
+
+The skill does not execute the runner's install command. The skill does not write CI config. The skill does not configure agent-side hooks (`.claude/settings.json`) — different surface, deferred.
+
+Documentation discipline rules apply at write time:
+- No emoji anywhere in scaffolded config or AGENTS.md update.
+- No version stamps or DRAFT markers.
+- Quality Gates section opens with the operational rule (gates are deterministic) before listing the gates.
+- One scope: Quality Gates. No duplication of ARCHITECTURE.md or ADR rationale.
+- No commented-out scripts. No orphan TODO / FIXME.
+</output_contract>

package/src/skills/codex/agentic-hooks/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: agentic-hooks
+  short_description: Scaffold deterministic quality gates per WORKFLOW §11 (pre-commit / pre-push). Detect-then-recommend Husky / lefthook / pre-commit / native; never silently pick.
+policy:
+  allow_implicit_invocation: false

package/src/skills/codex/agentic-philosophy/SKILL.md

@@ -10,7 +10,7 @@ Six behaviors apply to every non-trivial change. Bias toward caution over speed;
 <instructions>
 **Think Before Coding.** Don't assume. Don't hide confusion. Surface tradeoffs. State assumptions explicitly; ask when uncertain. If multiple interpretations exist, present them — don't pick silently. If a simpler approach exists, say so. If something is unclear, stop, name the confusion, ask.
 
-**Ground Before Coding.** Anchor in real patterns. Find the canonical/idiomatic way; note where you deviate and why. Find an existing example in the codebase and reuse its structure. Cite specific files, not "the codebase". Fetch via tools — don't dump code into context. For non-trivial changes, explore → plan → implement → commit. Skip for diffs describable in one sentence.
+**Ground Before Coding.** Anchor in real patterns before writing code. For non-trivial changes, invoke `/agentic-ground` — the workflow-operational skill that runs the four-source research pass (official docs, validated open-source examples, in-repo patterns, git history) and synthesizes a happy path with citations. The skill carries the prescriptive deviation gate; this section carries posture only. Skip for diffs describable in one sentence.
 
 **Simplicity First.** Minimum code that solves the problem. No features beyond what was asked. No abstractions for single-use code. No "flexibility" or "configurability" that wasn't requested. No error handling for impossible scenarios. Comments justify why, not what. No commented-out code; no orphan `TODO`/`FIXME` without an issue/ADR/follow-up reference. If 200 lines could be 50, rewrite.