@alexandrealvaro/agentic 0.6.0-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.
 
@@ -118,7 +119,7 @@ The kit ships nine universal skills plus three conditional ones — twelve discr
 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; CI + hooks (deferred — see Task 0013) will eventually enforce the gates that today are advisory.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.6.0-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-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/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