@alexandrealvaro/agentic 0.3.0-beta.2 → 0.5.0-beta.1

package/README.md

@@ -31,10 +31,12 @@ Two categories ([ADR-0007](doc/adr/0007-workflow-operational-skills.md)) and two
 | `agentic-bootstrap` | spec-driven | universal | Scans the repo, writes `AGENTS.md` ≤150 lines | `/agentic-bootstrap` |
 | `agentic-architecture` | spec-driven | universal | Scans the code, writes `ARCHITECTURE.md` | `/agentic-architecture` |
 | `agentic-adr` | spec-driven | universal | Drafts `doc/adr/NNNN-<slug>.md` from the conversation | `/agentic-adr` |
-| `agentic-task` | spec-driven | universal | Drafts `doc/tasks/NNNN-<slug>.md` (checkbox + Notes format) | `/agentic-task` |
+| `agentic-spec` | spec-driven | universal | Drafts `doc/specs/NNNN-<slug>.md` — feature-level spec (User Scenarios, Requirements, Success Criteria) layer 2 of the four-layer stack | `/agentic-spec` |
+| `agentic-task` | spec-driven | universal | Drafts `doc/tasks/NNNN-<slug>.md` (checkbox + Notes format; carries `Spec ref` to link the implementing spec) | `/agentic-task` |
 | `agentic-audit` | spec-driven | universal | Read-only drift report (AGENTS.md / ARCHITECTURE.md / ADRs) | `/agentic-audit` |
 | `agentic-philosophy` | workflow-operational | universal | Universal agent guardrails — auto-loads on non-trivial work | implicit |
 | `agentic-review` | workflow-operational | universal | Fresh-context code review per WORKFLOW §10; structured findings, no "approve" | `/agentic-review <range>` |
+| `agentic-ground` | workflow-operational | universal | Four-source pre-implementation research (docs / OSS / in-repo / git history) + happy-path synthesis + deviation gate per WORKFLOW §4 + §5 | `/agentic-ground` |
 | `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` |
@@ -119,6 +121,10 @@ Prompts reference templates by relative path. Two ways to give your agent access
 
 **Reviewing your own diff.** Run `/agentic-review <range>` (e.g. `/agentic-review main..HEAD` or `/agentic-review PR#42`). The skill assembles the diff, the relevant spec slice (`AGENTS.md`, applicable ADRs, the task's Acceptance Criteria), and delegates to a fresh-context reviewer subagent — no inherited bias from the session that wrote the code (WORKFLOW §10). Returns structured findings grouped Blocker / Concern / Note. Codex variant uses `/clear` + paste handoff since Codex has no subagent primitive.
 
+**Researching before implementation.** Run `/agentic-ground` (or let it auto-trigger on non-trivial work). The skill runs a four-source levantamento — official docs, validated open-source examples, in-repo patterns, and git history — synthesizes a happy path with citations from each source, and gates any deviation behind an irrefutable justification before code is written (WORKFLOW §4 + §5). Output is the input to whatever produces the implementation plan; the skill does not write code.
+
+**Specifying a feature.** Run `/agentic-spec` (or `/agentic-spec` with a feature name). The skill scaffolds `doc/specs/NNNN-<slug>.md` with industry-aligned mandatory sections (User Scenarios, Functional / Non-functional Requirements, Success Criteria, Edge Cases, Out of Scope, Open Questions, Related). Specs are layer 2 of the four-layer artifact stack — Constitution → Spec → Plan/Decisions → Code. One spec per feature; multiple tasks (`/agentic-task`) implement one spec; the task template carries a `Spec ref` field linking back to the spec.
+
 **Project already built with agents.** Treat missing artifacts as brownfield (run the relevant skill) and existing artifacts as audit (`/agentic-audit`).
 
 ## What ends up in your target project

package/WORKFLOW.md

@@ -30,15 +30,24 @@ What to keep in mind:
 
 ## 1. Spec-Driven Design
 
-Define the rules before the agent writes a line. The temptation is to dump everything into `AGENTS.md` and hope it works — but bloat causes the model to ignore the file. Keep one topic per Markdown file: lean and focused. And treat the three kinds of context as distinct artifacts with distinct jobs.
+Define the rules before the agent writes a line. The temptation is to dump everything into `AGENTS.md` and hope it works — but bloat causes the model to ignore the file. Keep one topic per Markdown file: lean and focused.
 
-**Operational context is advisory.** `AGENTS.md` (or `CLAUDE.md` for Claude Code, which can mirror or import the same content via `@AGENTS.md`) tells the agent how to build, test, follow conventions, and where the security boundaries are. The agent reads it as a guide, not a contract. Open standard `AGENTS.md` is native in most agentic IDEs.
+There are two complementary frames for the artifacts the kit produces. The first is **purpose** — what each artifact is *for*. The second is **loading mechanism** — when each artifact reaches the agent's context.
 
-**Canonical specs are constraints, not advice.** `DESIGN.md` (the visual contract — YAML tokens plus Markdown rationale, per Google Labs' open standard), `ARCHITECTURE.md` (system patterns and boundaries), and ADRs in `doc/adr/*.md` (Michael Nygard's pattern, with status lifecycle and superseded markers) are facts the agent must obey. If a token or pattern isn't declared here, it doesn't exist. The agent must never invent one.
+### Four-layer artifact stack (purpose)
 
-**On-demand context is `SKILL.md`.** Description loads at session start (the listing is capped at 1,536 characters per the spec) and body loads only when the skill is invoked. Use it for repeatable workflows or domain knowledge that shouldn't pay a token cost on every turn.
+1. **Constitution** — `AGENTS.md` (operational guide) and `WORKFLOW.md` (engineering philosophy). Tells the agent how the project works and how the team thinks. Read every session.
+2. **Spec** — `doc/specs/NNNN-<slug>.md`. Feature-level requirements: who the feature is for, what it must do, the measurable success criteria, the explicit non-goals. One spec per feature; multiple tasks implement one spec; ADRs may be driven by spec constraints. Industry-aligned with [GitHub Spec Kit](https://github.com/github/spec-kit).
+3. **Plan / Decisions** — `ARCHITECTURE.md` (system patterns and boundaries), `doc/adr/NNNN-*.md` (binding architectural decisions in Michael Nygard's pattern), `doc/tasks/NNNN-*.md` (per-work-unit plan with checkbox acceptance criteria). The *how* of building what the spec asked for.
+4. **Code** — the implementation. Code is the primary documentation of behavior; comments justify non-obvious choices.
 
-Two rules apply across all three:
+### Three context types (loading mechanism)
+
+- **Operational context is advisory.** `AGENTS.md` (or `CLAUDE.md` for Claude Code, which can mirror or import the same content via `@AGENTS.md`) tells the agent how to build, test, follow conventions, and where the security boundaries are. The agent reads it as a guide, not a contract. Open standard `AGENTS.md` is native in most agentic IDEs.
+- **Canonical specs are constraints, not advice.** `DESIGN.md` (the visual contract — YAML tokens plus Markdown rationale, per Google Labs' open standard), `ARCHITECTURE.md`, ADRs in `doc/adr/*.md`, and feature specs in `doc/specs/*.md` are facts the agent must obey. If a token, pattern, or success criterion isn't declared here, it doesn't exist. The agent must never invent one.
+- **On-demand context is `SKILL.md`.** Description loads at session start (the listing is capped at 1,536 characters per the spec) and body loads only when the skill is invoked. Use it for repeatable workflows or domain knowledge that shouldn't pay a token cost on every turn.
+
+Two rules apply across all of the above:
 
 - **Acceptance criteria must be measurable.** "Build a dashboard" fails. "Loads in under 2 seconds, shows 6 months of history, passes axe accessibility" succeeds.
 - **Prune.** If removing a line wouldn't make the agent fail, cut it.
@@ -89,6 +98,8 @@ Then check continuously, especially mid-implementation:
 
 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.
+
 ## 5. Ground in Real Patterns
 
 Don't dump the codebase into context. Anchor the model in a specific, project-relevant example.
@@ -97,6 +108,8 @@ Don't dump the codebase into context. Anchor the model in a specific, project-re
 
 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.
 
+`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.
+
 ## 6. Explore → Plan → Implement → Commit
 
 For non-trivial changes, four phases:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.3.0-beta.2",
+  "version": "0.5.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

@@ -48,9 +48,11 @@ export const REQUIRED_SKILLS = [
   'agentic-philosophy',
   'agentic-architecture',
   'agentic-adr',
+  'agentic-spec',
   'agentic-task',
   'agentic-audit',
   'agentic-review',
+  'agentic-ground',
 ];
 
 /**
@@ -263,9 +265,11 @@ export async function initCommand(opts) {
       '/agentic-bootstrap (AGENTS.md)',
       '/agentic-architecture (ARCHITECTURE.md)',
       '/agentic-adr',
+      '/agentic-spec (doc/specs/)',
       '/agentic-task',
       '/agentic-audit',
       '/agentic-review (WORKFLOW §10)',
+      '/agentic-ground (WORKFLOW §4 + §5)',
       ...(optedSkills.includes('agentic-design') ? ['/agentic-design (DESIGN.md)'] : []),
       ...(optedSkills.includes('agentic-subagent') && agents.includes('claude-code')
         ? ['/agentic-subagent']

package/src/lib/rootdoc.js

@@ -17,11 +17,15 @@ export const SKILL_DESCRIPTIONS = {
     'Universal agent guardrails (think before coding, verify before claiming done). Auto-loads on non-trivial work.',
   'agentic-architecture': 'Generate or audit `ARCHITECTURE.md` at the repo root.',
   'agentic-adr': 'Draft a new ADR at `doc/adr/NNNN-<slug>.md`.',
+  'agentic-spec':
+    'Draft a feature spec at `doc/specs/NNNN-<slug>.md` (Spec Kit-aligned mandatory sections). Layer 2 of the four-layer artifact stack.',
   'agentic-task': 'Draft a new task at `doc/tasks/NNNN-<slug>.md`.',
   'agentic-audit':
     'Read-only drift report comparing AGENTS.md / ARCHITECTURE.md / ADRs against the code.',
   'agentic-review':
     'Fresh-context code review per WORKFLOW §10 — assemble handoff, return structured findings.',
+  'agentic-ground':
+    'Four-source pre-implementation research (docs / OSS / in-repo / git history) + happy-path synthesis + deviation gate. WORKFLOW §4 + §5.',
   '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.',

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

@@ -0,0 +1,100 @@
+---
+name: agentic-ground
+description: Four-source pre-implementation research — official docs, validated open-source examples, in-repo patterns, and git history — then synthesize a happy path and gate any deviation with an irrefutable justification before code is written. Auto-invokes on non-trivial work, refactors, library or pattern selection, "research before coding", "before implementing", "which library", "which pattern", "how to approach", "ground before coding". Workflow-operational counterpart to WORKFLOW.md §4 (Find the Happy Path) and §5 (Ground in Real Patterns); pairs with agentic-philosophy (posture) and agentic-review (post-implementation §10 review).
+allowed-tools: Read, Glob, Grep, Bash, WebFetch, WebSearch
+---
+
+# /agentic-ground
+
+Implements WORKFLOW §4 + §5 end-to-end as a single research pass. The four sources are joined by **AND**, not OR — every non-trivial change runs the full levantamento, then synthesizes a happy path, then justifies any deviation. Output is the input to whatever skill or freeform turn produces the implementation plan; this skill does not write code.
+
+## Step 0 — Scope the recortte
+
+Confirm what is being researched. The recortte is the smallest verifiable surface that captures the change: a function to add, a library to pick, a pattern to apply. State it in one sentence before research starts. If the surface is broader than one sentence captures, ask the user to narrow it; broad recorttes produce diluted research.
+
+If the change is genuinely trivial (rename, typo, one-line refactor on a tested path), skip this skill.
+
+## Step 1 — Four-source levantamento (all four required)
+
+### Source A — official documentation
+
+For each language and library in scope, cite the canonical doc URL and version. Use `WebFetch` to confirm the page exists and read the relevant section; use `WebSearch` to locate it if the URL is unknown. If neither produces a confident hit, ask the user for a known-good link rather than fabricating one. Output: bulleted citations, one per language/library, each with URL plus a one-line summary of the relevant guidance.
+
+### Source B — validated open-source examples
+
+Find ≥1 (prefer 2–3) public repository solving the same *technical* recortte with similar techniques. The match is technical, not domain — a CRUD-app-with-auth and a CLI-with-auth both hit "auth flow", and either is valid for the auth recortte. Use `WebSearch` (e.g. `site:github.com <recortte> language:<lang>`) and follow up with `WebFetch` of the specific file. Cite `<repo>:<path>:<line-range>` and quote the relevant block — never paraphrase code from training memory. If search is inconclusive, ask the user for a known reference.
+
+### Source C — in-repo examples
+
+Grep / glob the current repo for analogous patterns. Cite `<file>:<line>` plus a one-line description of how the existing example handles the same shape. If the codebase has no analog, state that explicitly (real signal, not a gap).
+
+### Source D — git history
+
+Run `git log --all --oneline -- <relevant-paths>`, `git log --all --grep=<keyword>`, and a sweep of sibling active branches (`git branch -a`, then `git log <branch> -- <paths>` on those that look related). Surface any prior attempt or sibling solution — including abandoned ones — with `<commit-sha>` plus the touching file path and a one-line description. If the search is genuinely empty, state "no prior attempt found" — that is the valid Source D outcome when there isn't one. Narrow with `--grep` or `-S` on multi-thousand-commit repos.
+
+## Step 2 — Happy path synthesis
+
+In one paragraph, name the most-grounded approach for the recortte and cite at least one source per Source A / B / C. Source D is included when it produced a hit; otherwise mark "no prior attempt found." The paragraph is the canonical answer the engineer would give if asked "what is the canonical, idiomatic way to solve this here?" — the question WORKFLOW.md §4 frames.
+
+## Step 3 — Deviation gate
+
+If the implementation the user (or you) is about to write deviates from the synthesized happy path, write the justification before any code lands. The justification must name the specific constraint, evidence, or trade-off forcing the deviation — generic "we want it differently" is insufficient. If the justification cannot be written confidently, loop back to Step 1 and look harder; do not deviate without it.
+
+The gate is prescriptive, not descriptive: WORKFLOW §4 asks "was the deviation deliberate?"; this gate asks "is the deviation defensible against the four sources?" Write the answer down.
+
+## Step 4 — Confidence checkpoint
+
+Before handing off to implementation, report a soft verdict against four checks:
+
+- A consulted (≥1 official-doc citation per language/library)
+- B consulted (≥1 OSS citation, with cite-and-fetched code)
+- C consulted (in-repo analog cited or "no analog found" stated)
+- D checked (commits / branches surveyed; hit cited or "no prior attempt found")
+- Happy path declared (Step 2)
+- Deviation, if any, justified (Step 3)
+
+If any check fails, surface the gap to the user and ask before proceeding rather than blocking. The user retains the authority to skip; the discipline is in surfacing, not in enforcement.
+
+## Output contract
+
+A single message structured as:
+
+```
+## Recortte
+<one sentence>
+
+## Source A — official documentation
+- <lang/lib>: <URL@version> — <one-line summary>
+
+## Source B — validated open-source examples
+- <repo>:<path>:<line-range> — <one-line summary>
+  ```
+  <quoted code block>
+  ```
+
+## Source C — in-repo examples
+- <file>:<line> — <one-line summary>
+- (or: "no analog found in the codebase")
+
+## Source D — git history
+- <commit-sha> <touching-path> — <one-line summary>
+- (or: "no prior attempt found")
+
+## Happy path
+<one paragraph synthesizing A + B + C + D, with citations>
+
+## Proposed implementation vs happy path
+- aligned: <what stays canonical>
+- deviates: <list of deviations>
+  - <deviation>: <irrefutable justification>
+
+## Confidence checkpoint
+- A consulted: yes / no — <gap if no>
+- B consulted: yes / no — <gap if no>
+- C consulted: yes / no — <gap if no>
+- D checked: yes / no — <gap if no>
+- happy path declared: yes
+- deviations justified: yes / no / n.a.
+```
+
+No code is written by this skill. The output feeds the next turn (or `/agentic-task`, `/agentic-philosophy`'s Goal-Driven Execution, or freeform implementation).

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

@@ -0,0 +1,125 @@
+---
+name: agentic-spec
+description: Draft a feature-level specification at doc/specs/NNNN-<slug>.md following the kit's four-layer artifact stack (Constitution → Spec → Plan/Decisions → Code). Adapts GitHub Spec Kit's mandatory sections (User Scenarios, Requirements, Success Criteria) to the kit's documentation discipline. Use when the user wants to write, draft, scaffold, or open a feature spec, PRD, product requirements, feature brief, user stories, or success criteria for a feature multiple tasks will implement. Status starts at draft; the file is the binding feature contract once accepted.
+allowed-tools: Read, Write, Glob, Bash
+---
+
+# /agentic-spec
+
+Drafts `doc/specs/<NNNN>-<short-slug>.md` for one feature. Status lifecycle: `draft` → `accepted` → `shipped` | `superseded by SPEC-NNNN`. Spec is the layer-2 artifact in the kit's four-layer stack — Constitution (`AGENTS.md` + `WORKFLOW.md`) → **Spec (this skill)** → Plan/Decisions (`ARCHITECTURE.md` + `doc/adr/` + `doc/tasks/`) → Code. Multiple tasks implement one spec; ADRs may be driven by spec constraints.
+
+## Step 1 — Determine NNNN and slug
+
+List `doc/specs/`. NNNN = next available 4-digit number after the highest existing (mirrors the ADR and task conventions). If `doc/specs/` does not exist, create it; start at `0001`. Slug: kebab-case, ≤6 words, derived from the feature title.
+
+## Step 2 — Confirm scope
+
+The spec captures **one** feature. If the user's request implies multiple features, ask which one to write first; the others become follow-up specs. A "feature" here is the smallest user-visible outcome that has its own success criteria — not a task (work unit) and not a binding architectural decision (ADR).
+
+## Step 3 — Interview to fill
+
+Ask one question per missing field, in this order. Skip the philosophical questions and the questions whose answers are already obvious from the conversation.
+
+* **Context:** business context first per ADR-0008. *Why* the feature exists, the user / constraint / problem it addresses, the cost of *not* building it.
+* **User Scenarios:** Given-When-Then for the key flows. Each scenario must be independently testable. Multiple scenarios when the feature has more than one path.
+* **Functional Requirements:** testable statements. Each as a checkbox. *"User can sign in with email and password"* — yes. *"Authentication should be secure"* — no, that's not a requirement, it's a hope.
+* **Non-functional Requirements:** performance, security, accessibility, observability — only the constraints that bind. Skip when there are none.
+* **Success Criteria:** measurable per [`WORKFLOW.md` §1](../../WORKFLOW.md). Each as a checkbox. Pass/fail must be observable, not aspirational. *"Loads in under 2 seconds at p95 over 7 days"* — yes. *"Loads fast"* — no.
+* **Edge Cases:** empty inputs, large inputs, concurrent access, missing prerequisites, permission errors. Surface them before code is written, not after a bug report.
+* **Out of Scope:** explicit non-goals. Anything readers might assume is in scope but isn't. Prevents scope creep without an audit trail.
+* **Open Questions:** deferred decisions. Each becomes a follow-up ADR or an explicit punt with a rationale.
+* **Related:** ADRs touched by this spec, tasks implementing it (filled lazily as tasks are created), other specs this one supersedes or depends on.
+
+Status starts at `draft`. Created: today, ISO format. Owner: ask. Do **not** invent values — when the user does not know, leave `<TODO>` and ask.
+
+## Step 4 — Write the file
+
+Path: `doc/specs/<NNNN>-<short-slug>.md`. Use the template below.
+
+Stop after writing. Do **not** flip status to `accepted` — that requires user review.
+
+## Step 5 — Editing guidance for later turns
+
+When the user later works on the spec, edit the file by:
+
+* Toggling Success Criteria checkboxes as feature lands incrementally.
+* Appending to **Open Questions** (close them with the resolution; never delete them).
+* Flipping `Status` to `accepted` once the user signs off and tasks start being created.
+* Flipping `Status` to `shipped` after release.
+* Flipping `Status` to `superseded by SPEC-NNNN` when a later spec replaces this one.
+* Adding `Tasks` entries to `Related` as tasks are created against this spec.
+
+Never rewrite existing prose — append rationale to **Open Questions** as a resolution paragraph rather than mutating the original requirement text.
+
+## Template — `doc/specs/NNNN-<slug>.md`
+
+````markdown
+# Spec `<NNNN>`: `<short imperative title>`
+
+**Status:** `<draft | accepted | shipped | superseded by SPEC-NNNN>`
+**Created:** `<YYYY-MM-DD>`
+**Owner:** `<name or role>`
+
+## Context
+
+`<Why this feature exists. The user, the constraint, the problem. What would break if this feature did not ship.>`
+
+## User Scenarios
+
+`<Given-When-Then for the key flows. Each scenario independently testable.>`
+
+- **Scenario 1:** `<short title>`
+  - Given `<starting state>`
+  - When `<action>`
+  - Then `<observable outcome>`
+
+## Requirements
+
+### Functional
+
+- [ ] `<R1: testable statement>`
+- [ ] `<R2>`
+
+### Non-functional
+
+- [ ] `<perf / security / a11y / observability — only when binding>`
+
+## Success Criteria
+
+Measurable conditions. Each as a checkbox; pass/fail observable, not aspirational.
+
+- [ ] `<criterion 1: measurable, observable>`
+- [ ] `<criterion 2>`
+
+## Edge Cases
+
+- `<empty input behavior>`
+- `<large input / failure modes>`
+- `<permission / concurrency / state-restoration cases>`
+
+## Out of Scope
+
+`<Explicit non-goals. Anything readers might assume is in scope but isn't.>`
+
+## Open Questions
+
+`<Deferred decisions. Each becomes an ADR or a documented punt.>`
+
+## Related
+
+- ADRs: `<list with links — written as the spec is accepted>`
+- Tasks: `<doc/tasks/NNNN-... — appended as tasks are created>`
+- Supersedes / Depends on: `<other spec links if any>`
+````
+
+## Output contract
+
+A single new file at `doc/specs/<NNNN>-<short-slug>.md`. Status `draft`. Tasks list empty (filled lazily as tasks land). No existing specs modified. No invented values.
+
+The spec is a narrative document but is exempt from ADR-0008's no-dates rule for the same reason ADRs and tasks are: the `Status` lifecycle and `Created` field are part of the auditability primitive. The remaining documentation discipline rules apply at write time:
+
+- No emoji anywhere in the file.
+- `Context` is the business-context-first section — *why* the feature exists before *what* it does.
+- One scope: one feature per spec. Multiple features implies multiple specs.
+- No speculation. Open Questions go in their named section; everywhere else captures decisions.
+- No commented-out requirements or TODO/FIXME — every deferred item references a tracked work item or lives under Open Questions.

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

@@ -20,6 +20,7 @@ Ask one question per missing field, in this order:
 * **Acceptance Criteria:** measurable conditions. Each is a checkbox; pass/fail must be observable, not aspirational ("loads in under 2s", not "fast enough").
 * **Plan:** concrete sequential steps with file paths where applicable. Each is a checkbox.
 * **Owner:** ask.
+* **Spec ref:** ask; leave blank when no spec drives this task. When a feature spec exists at `doc/specs/NNNN-<slug>.md`, link it here so the spec's `Related → Tasks` list reciprocates.
 * **Board ref:** ask; leave blank if solo work.
 
 Status starts at `proposed`. Created: today, ISO format. Notes: empty (filled during execution). Definition of Done section: copy verbatim from the template.
@@ -48,7 +49,8 @@ Status flips to `done` only when every Acceptance Criterion and every Definition
 **Status:** `<proposed | in-progress | blocked | done>`
 **Created:** `<YYYY-MM-DD>`
 **Owner:** `<name or role>`
-**Board ref:** `<external ticket URL or ID — leave blank for solo work>`
+**Spec ref:** `<doc/specs/NNNN-<slug>.md or SPEC-NNNN — blank when no spec drives this task>`
+**Board ref:** `<external ticket URL or ID — blank for solo work>`
 
 ## Context
 

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

@@ -0,0 +1,82 @@
+---
+name: agentic-ground
+description: Four-source pre-implementation research — official docs, validated open-source examples, in-repo patterns, and git history — then synthesize a happy path and gate any deviation with an irrefutable justification before code is written. Auto-invokes on non-trivial work, refactors, library or pattern selection, "research before coding", "before implementing", "which library", "which pattern", "how to approach", "ground before coding". Workflow-operational counterpart to WORKFLOW.md §4 (Find the Happy Path) and §5 (Ground in Real Patterns).
+---
+
+<background_information>
+Implements WORKFLOW §4 + §5 end-to-end as one research pass. The four sources are joined by AND, not OR — every non-trivial change runs the full levantamento, then synthesizes a happy path, then justifies any deviation. Output is the input to whatever skill or freeform turn produces the implementation plan; this skill does not write code.
+
+Codex auto-trigger on description keywords is less mature than Claude Code's. If auto-invocation does not fire on a non-trivial change, invoke this skill manually before implementing.
+</background_information>
+
+<instructions>
+Step 0 — scope the recortte. Confirm what is being researched in one sentence. The recortte is the smallest verifiable surface that captures the change: a function to add, a library to pick, a pattern to apply. If broader than one sentence, ask the user to narrow. Skip the skill on genuinely trivial diffs (rename, typo, one-line refactor on a tested path).
+
+Step 1 — four-source levantamento, all four required:
+
+Source A — official documentation. For each language and library in scope, cite the canonical doc URL and version. Read the relevant section. Ask the user for a known-good link rather than fabricating one. Output: bulleted citations, one per language/library, each with URL plus a one-line summary.
+
+Source B — validated open-source examples. ≥1 (prefer 2–3) public repository solving the same technical recortte with similar techniques. Match is technical, not domain. Cite `<repo>:<path>:<line-range>` and quote the relevant block — never paraphrase from training memory. If search is inconclusive, ask the user for a known reference.
+
+Source C — in-repo examples. Grep / glob for analogous patterns. Cite `<file>:<line>` plus a one-line description of how the existing example handles the same shape. If the codebase has no analog, state that explicitly.
+
+Source D — git history. Run `git log --all --oneline -- <relevant-paths>`, `git log --all --grep=<keyword>`, sweep sibling active branches. Cite `<commit-sha>` plus touching file path and a one-line description. If empty, state "no prior attempt found." Narrow with `--grep` or `-S` on multi-thousand-commit repos.
+
+Step 2 — happy path synthesis. In one paragraph, name the most-grounded approach for the recortte and cite at least one source per Source A / B / C. Source D included when it produced a hit; otherwise mark "no prior attempt found." The paragraph is the canonical answer to "what is the canonical, idiomatic way to solve this here?"
+
+Step 3 — deviation gate. If the implementation about to be written deviates from the happy path, write the justification first. Must name the specific constraint, evidence, or trade-off forcing the deviation — generic "we want it differently" is insufficient. If the justification cannot be written confidently, loop back to Step 1 and look harder; do not deviate without it. Prescriptive gate, not descriptive — write the answer down.
+
+Step 4 — confidence checkpoint. Soft verdict on:
+- A consulted (≥1 official-doc citation per language/library)
+- B consulted (≥1 OSS citation, with cite-and-fetched code)
+- C consulted (in-repo analog cited or "no analog found" stated)
+- D checked (commits / branches surveyed; hit cited or "no prior attempt found")
+- Happy path declared (Step 2)
+- Deviation, if any, justified (Step 3)
+
+If any check fails, surface the gap to the user and ask before proceeding. Do not block. The user retains authority to skip; the discipline is in surfacing.
+</instructions>
+
+<output_contract>
+A single message structured as:
+
+```
+## Recortte
+<one sentence>
+
+## Source A — official documentation
+- <lang/lib>: <URL@version> — <one-line summary>
+
+## Source B — validated open-source examples
+- <repo>:<path>:<line-range> — <one-line summary>
+  ```
+  <quoted code block>
+  ```
+
+## Source C — in-repo examples
+- <file>:<line> — <one-line summary>
+- (or: "no analog found in the codebase")
+
+## Source D — git history
+- <commit-sha> <touching-path> — <one-line summary>
+- (or: "no prior attempt found")
+
+## Happy path
+<one paragraph synthesizing A + B + C + D, with citations>
+
+## Proposed implementation vs happy path
+- aligned: <what stays canonical>
+- deviates: <list of deviations>
+  - <deviation>: <irrefutable justification>
+
+## Confidence checkpoint
+- A consulted: yes / no — <gap if no>
+- B consulted: yes / no — <gap if no>
+- C consulted: yes / no — <gap if no>
+- D checked: yes / no — <gap if no>
+- happy path declared: yes
+- deviations justified: yes / no / n.a.
+```
+
+No code is written by this skill. The output feeds the next turn or another skill.
+</output_contract>

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

@@ -0,0 +1,5 @@
+interface:
+  display_name: agentic-ground
+  short_description: Four-source pre-implementation research (docs / OSS / in-repo / git history) plus happy-path synthesis and deviation gate. WORKFLOW §4 + §5.
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,105 @@
+---
+name: agentic-spec
+description: Draft a feature-level specification at doc/specs/NNNN-<slug>.md following the four-layer artifact stack (Constitution → Spec → Plan/Decisions → Code). Adapts GitHub Spec Kit's mandatory sections (User Scenarios, Requirements, Success Criteria) to the kit's documentation discipline. Use when the user wants to write, draft, scaffold, or open a feature spec, PRD, product requirements, feature brief, user stories, or success criteria. Status starts at draft.
+---
+
+<background_information>
+Drafts `doc/specs/<NNNN>-<short-slug>.md` for one feature. Status lifecycle: draft → accepted → shipped | superseded by SPEC-NNNN. Spec is the layer-2 artifact in the kit's four-layer stack — Constitution (`AGENTS.md` + `WORKFLOW.md`) → Spec (this skill) → Plan/Decisions (`ARCHITECTURE.md` + `doc/adr/` + `doc/tasks/`) → Code. Multiple tasks implement one spec; ADRs may be driven by spec constraints.
+
+Codex auto-trigger on description keywords is less mature than Claude Code's. If auto-invocation does not fire when the user asks to "draft a spec" or "write a PRD" on a non-trivial feature, invoke this skill manually.
+</background_information>
+
+<instructions>
+Step 1 — determine NNNN and slug. List `doc/specs/`. NNNN = next available 4-digit number after the highest existing (mirrors ADR and task conventions). If `doc/specs/` does not exist, create it; start at 0001. Slug: kebab-case, ≤6 words, derived from the feature title.
+
+Step 2 — confirm scope. The spec captures one feature. If the user's request implies multiple, ask which to write first; the others become follow-up specs. A "feature" here is the smallest user-visible outcome that has its own success criteria — not a task (work unit) and not a binding architectural decision (ADR).
+
+Step 3 — interview to fill. Ask one question per missing field, in this order:
+- Context: business context first per ADR-0008. Why the feature exists, the user / constraint / problem it addresses, the cost of not building it.
+- User Scenarios: Given-When-Then for the key flows. Each scenario independently testable.
+- Functional Requirements: testable statements. Each as a checkbox.
+- Non-functional Requirements: perf / security / a11y / observability — only when binding.
+- Success Criteria: measurable per WORKFLOW.md §1. Each as a checkbox; pass/fail observable, not aspirational.
+- Edge Cases: empty inputs, large inputs, concurrent access, missing prerequisites, permission errors.
+- Out of Scope: explicit non-goals.
+- Open Questions: deferred decisions. Each becomes an ADR or a documented punt.
+- Related: ADRs touched, tasks implementing it (lazy), other specs this one supersedes or depends on.
+
+Status starts at draft. Created: today, ISO format. Owner: ask. Do NOT invent values; leave `<TODO>` and ask.
+
+Step 4 — write the file. Path: `doc/specs/<NNNN>-<short-slug>.md`. Use the template below.
+
+Stop after writing. Do NOT flip status to accepted — that requires user review.
+
+Step 5 — editing guidance for later turns. Toggle Success Criteria checkboxes as feature lands. Append to Open Questions; close with resolution paragraphs, never delete. Flip Status to accepted on user sign-off, shipped after release, superseded when replaced. Add tasks to Related as they are created. Never rewrite existing prose — append rationale to Open Questions rather than mutating original requirement text.
+</instructions>
+
+<template path="doc/specs/NNNN-<slug>.md">
+# Spec `<NNNN>`: `<short imperative title>`
+
+**Status:** `<draft | accepted | shipped | superseded by SPEC-NNNN>`
+**Created:** `<YYYY-MM-DD>`
+**Owner:** `<name or role>`
+
+## Context
+
+`<Why this feature exists. The user, the constraint, the problem. What would break if this feature did not ship.>`
+
+## User Scenarios
+
+`<Given-When-Then for the key flows. Each scenario independently testable.>`
+
+- **Scenario 1:** `<short title>`
+  - Given `<starting state>`
+  - When `<action>`
+  - Then `<observable outcome>`
+
+## Requirements
+
+### Functional
+
+- [ ] `<R1: testable statement>`
+- [ ] `<R2>`
+
+### Non-functional
+
+- [ ] `<perf / security / a11y / observability — only when binding>`
+
+## Success Criteria
+
+Measurable conditions. Each as a checkbox; pass/fail observable, not aspirational.
+
+- [ ] `<criterion 1: measurable, observable>`
+- [ ] `<criterion 2>`
+
+## Edge Cases
+
+- `<empty input behavior>`
+- `<large input / failure modes>`
+- `<permission / concurrency / state-restoration cases>`
+
+## Out of Scope
+
+`<Explicit non-goals. Anything readers might assume is in scope but isn't.>`
+
+## Open Questions
+
+`<Deferred decisions. Each becomes an ADR or a documented punt.>`
+
+## Related
+
+- ADRs: `<list with links — written as the spec is accepted>`
+- Tasks: `<doc/tasks/NNNN-... — appended as tasks are created>`
+- Supersedes / Depends on: `<other spec links if any>`
+</template>
+
+<output_contract>
+A single new file at `doc/specs/<NNNN>-<short-slug>.md`. Status draft. Tasks list empty (filled lazily as tasks land). No existing specs modified. No invented values.
+
+Spec is a narrative document but is exempt from ADR-0008's no-dates rule for the same reason ADRs and tasks are: the Status lifecycle and Created field are part of the auditability primitive. Remaining documentation discipline rules apply at write time:
+- No emoji anywhere in the file.
+- Context is the business-context-first section — why the feature exists before what it does.
+- One scope: one feature per spec.
+- No speculation. Open Questions go in their named section.
+- No commented-out requirements or TODO/FIXME — every deferred item references a tracked work item or lives under Open Questions.
+</output_contract>

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

@@ -0,0 +1,5 @@
+interface:
+  display_name: agentic-spec
+  short_description: Draft a feature spec at doc/specs/NNNN-<slug>.md (Spec Kit-aligned mandatory sections + the kit's documentation discipline).
+policy:
+  allow_implicit_invocation: false

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

@@ -15,6 +15,7 @@ Step 2 — interview to fill. Ask one question per missing field, in this order:
 - Acceptance Criteria: measurable conditions. Each is a checkbox; pass/fail must be observable, not aspirational ("loads in under 2s", not "fast enough").
 - Plan: concrete sequential steps with file paths where applicable. Each is a checkbox.
 - Owner: ask.
+- Spec ref: ask; leave blank when no spec drives this task. When a feature spec exists at `doc/specs/NNNN-<slug>.md`, link it here so the spec's Related → Tasks list reciprocates.
 - Board ref: ask; leave blank if solo work.
 
 Status starts at proposed. Created: today, ISO format. Notes: empty. Definition of Done section: copy verbatim from the template.
@@ -37,7 +38,8 @@ Status flips to done only when every Acceptance Criterion and every Definition o
 **Status:** `<proposed | in-progress | blocked | done>`
 **Created:** `<YYYY-MM-DD>`
 **Owner:** `<name or role>`
-**Board ref:** `<external ticket URL or ID — leave blank for solo work>`
+**Spec ref:** `<doc/specs/NNNN-<slug>.md or SPEC-NNNN — blank when no spec drives this task>`
+**Board ref:** `<external ticket URL or ID — blank for solo work>`
 
 ## Context
 

package/templates/task.md

@@ -3,7 +3,8 @@
 **Status:** `<proposed | in-progress | blocked | done>`
 **Created:** `<YYYY-MM-DD>`
 **Owner:** `<name or role>`
-**Board ref:** `<external ticket URL or ID — leave blank for solo work>`
+**Spec ref:** `<doc/specs/NNNN-<slug>.md or SPEC-NNNN — blank when no spec drives this task>`
+**Board ref:** `<external ticket URL or ID — blank for solo work>`
 
 ## Context