@alexandrealvaro/agentic 0.4.0-beta.1 → 0.5.0-beta.1

package/README.md

@@ -31,7 +31,8 @@ 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>` |
@@ -122,6 +123,8 @@ Prompts reference templates by relative path. Two ways to give your agent access
 
 **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.4.0-beta.1",
+  "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,6 +48,7 @@ export const REQUIRED_SKILLS = [
   'agentic-philosophy',
   'agentic-architecture',
   'agentic-adr',
+  'agentic-spec',
   'agentic-task',
   'agentic-audit',
   'agentic-review',
@@ -264,6 +265,7 @@ 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)',

package/src/lib/rootdoc.js

@@ -17,6 +17,8 @@ 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.',

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-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