@alexandrealvaro/agentic 0.1.0-beta.1 → 0.2.0-beta.1

package/README.md

@@ -2,106 +2,127 @@
 
 A starter kit for engineering production code with LLMs. Lean templates and init prompts grounded in established standards: [Anthropic Skills](https://code.claude.com/docs/en/skills), [Claude Code subagents](https://code.claude.com/docs/en/sub-agents), [agents.md](https://agents.md), Nygard ADRs, and [Google Labs DESIGN.md](https://github.com/google-labs-code/design.md).
 
-> **Status:** v0.1.0-beta — early. The CLI works for AGENTS.md bootstrap (`npx @alexandrealvaro/agentic@beta init`); other artifact commands are in development. The manual workflow below stays fully usable for everything. Report rough edges via [GitHub Issues](https://github.com/alexandremendoncaalvaro/agentic-development/issues).
+> **Status:** v0.2 in development on the `cli` branch — the CLI installs the full skill set (universal: `agentic-bootstrap`, `agentic-philosophy`, `agentic-architecture`, `agentic-adr`, `agentic-task`, `agentic-audit`, `agentic-review`; conditional: `agentic-design` for frontend, `agentic-subagent` for Claude Code, `agentic-skill` opt-in) into Claude Code or Codex. Each skill produces its artifact (or runs its operation) via the agent's native conversational UI. v0.1.0-beta on npm still prints prompts; the v0.2 release ships once the polish chunk lands. Report rough edges via [GitHub Issues](https://github.com/alexandremendoncaalvaro/agentic-development/issues).
 
 ## Prerequisites
 
 An agentic coding tool that reads markdown files. Examples here use **Claude Code** and **Codex CLI** (primary tools the author uses); the kit also works with [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), Cursor, Continue, Aider, and any other tool that follows the [agents.md](https://agents.md) open standard.
 
-For the CLI path: Node.js 18+ (only needed if you use `npx`/`npm install`; the manual workflow has no runtime dependencies).
+For the CLI path: Node.js 18+. The CLI is the recommended path. Paste-into-agent prompts (see [Manual prompts](#manual-prompts) below) remain as an alternative for users who don't want to run an installer — same artifacts, same patterns.
 
-## What's here
+For the philosophy and full reasoning behind the kit, see [WORKFLOW.md](WORKFLOW.md).
 
-- **[WORKFLOW.md](WORKFLOW.md)** — the philosophy: how to engineer with LLMs without vibe-coding. Read this first.
-- **[templates/](templates/)** — pure templates. Copy and fill, or have your agent fill them via the matching prompt.
-- **[prompts/](prompts/)** — init prompts to paste into your agent. Each generates one artifact from its template.
-
-## How to use
-
-This kit is a **reference repository, not a per-project dependency.** Templates and prompts stay here; only the generated artifacts (AGENTS.md, ARCHITECTURE.md, ADRs, etc.) end up in your target project. The pattern matches how [GitHub's spec-kit](https://github.com/github/spec-kit) and [cookiecutter](https://cookiecutter.readthedocs.io/) handle distribution — templates in one place, outputs in another, never mixed.
-
-### Quickstart (CLI, beta)
-
-For AGENTS.md bootstrap, the fastest path is the CLI — no clone needed:
+## Install & use
 
 ```bash
 cd your-project
 npx @alexandrealvaro/agentic@beta init
 ```
 
-The CLI auto-detects greenfield/brownfield/audit mode, then prints a self-contained prompt (templates inlined) for you to paste into your agent. Add `--mode greenfield|brownfield|audit` to override detection.
+The CLI installs the universal skill set into your agent's native location, plus conditional skills based on what your project needs:
 
-> **Beta scope:** Only `init` (AGENTS.md) is in v0.1.0-beta. For ARCHITECTURE.md, ADRs, design tokens, skills, and subagents, use the [manual workflow](#manual-workflow) below until those CLI commands ship.
+* **Claude Code:** `.claude/skills/<skill-name>/SKILL.md` (plus `.claude/agents/<name>.md` for skills that ship a subagent)
+* **Codex:** `.agents/skills/<skill-name>/SKILL.md` (+ `agents/openai.yaml`)
 
-### Manual workflow
+Two categories ([ADR-0007](doc/adr/0007-workflow-operational-skills.md)) and two installation modes (universal = always; conditional = depends on project signals or opt-in):
 
-Required for every artifact except AGENTS.md right now, and useful as a fallback for `init` if you want to run prompts directly without the CLI.
+| Skill | Category | Installs | What it does | Invoke |
+| --- | --- | --- | --- | --- |
+| `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-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-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` |
 
-#### Setup (once)
+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.
 
-1. Read [`WORKFLOW.md`](WORKFLOW.md) — the philosophy that everything else follows from.
-2. Clone this repo to a location outside your projects:
+If your project already has an `AGENTS.md` (or `CLAUDE.md`), the installer appends a managed `Skills installed by agentic` section bracketed by `<!-- agentic-managed-skills:start -->` / `:end -->` markers. User content outside those markers is byte-preserved; re-runs update only the managed block.
 
-   ```bash
-   git clone https://github.com/alexandremendoncaalvaro/agentic-development.git ~/dev/agentic-development
-   ```
+For persistent install:
 
-   **Never copy this kit into your target project.** Only the generated artifacts go there.
+```bash
+npm install -g @alexandrealvaro/agentic@beta
+agentic init
+```
 
-#### Give the agent access to templates
+## Manual prompts
 
-When you paste a prompt from `prompts/`, the agent needs to read the matching template in `templates/`. Two ways to grant access:
+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:
 
-- **Recommended** — start the agent with the kit added. In Claude Code, from your target project's directory:
-  ```
-  claude --add-dir <path-to-this-kit>
-  ```
-  The agent can then read templates via the relative paths the prompts use.
-- **Standalone** — copy the content of both `prompts/<X>.md` and `templates/<X>.md` into the agent session. No setup, slightly more friction.
+| Artifact | Prompt | Template | Lives at |
+| --- | --- | --- | --- |
+| `AGENTS.md` | [prompts/agents.md](prompts/agents.md) | [agents-project](templates/agents-project.md) | repo root |
+| `ARCHITECTURE.md` | [prompts/architecture.md](prompts/architecture.md) | [architecture](templates/architecture.md) | repo root |
+| ADR | [prompts/adr.md](prompts/adr.md) | [adr](templates/adr.md) | `doc/adr/NNNN-<title>.md` |
+| Task | [prompts/task.md](prompts/task.md) | [task](templates/task.md) | `doc/tasks/NNNN-<slug>.md` |
+| `DESIGN.md` | [prompts/design.md](prompts/design.md) | (no template — bootstrap from existing tokens) | repo root |
+| Skill | [prompts/skill.md](prompts/skill.md) | [skill](templates/skill.md) | `.claude/skills/<name>/SKILL.md` |
+| Subagent | [prompts/subagent.md](prompts/subagent.md) | [subagent](templates/subagent.md) | `.claude/agents/<name>.md` |
+
+Prompts reference templates by relative path. Two ways to give your agent access:
 
-#### Workflows by scenario
+- **Browse on GitHub.** Open the prompt and template files in tabs, copy both into your agent session. No install.
+- **Use the npm-installed package as a kit folder.** If you ran `npm install -g @alexandrealvaro/agentic@beta`, the kit is already on disk. For Claude Code from your project's directory:
+  ```bash
+  claude --add-dir "$(npm root -g)/@alexandrealvaro/agentic"
+  ```
+  The agent then reads the templates locally via the paths the prompts use.
 
-**New project (greenfield).** Initialize git and set up the project structure, then paste `prompts/agents.md`. The agent interviews you about stack, build, test, conventions, and security boundaries, then writes `AGENTS.md` at the repo root. As architectural and design decisions emerge, use `prompts/architecture.md`, `prompts/adr.md`, `prompts/design.md`, `prompts/skill.md`, and `prompts/subagent.md` for each new artifact.
+## Workflows by scenario
 
-**Existing project (brownfield).** Same prompts. The project-wide ones (`prompts/agents.md`, `prompts/architecture.md`) instruct the agent to read the codebase, verify what you told them, and flag any mismatch before writing — so contradictions get surfaced instead of trusted. The per-artifact prompts (ADR, design, skill, subagent) work on a single decision or asset and don't need this verification. Backfill ADRs only for decisions that matter going forward; don't try to rewrite history.
+**New project (greenfield).** Initialize git and project structure, then run `agentic init` to install the universal skill set plus any auto-detected conditional skills. From inside Claude Code or Codex: `/agentic-bootstrap` produces `AGENTS.md`, `/agentic-architecture` produces `ARCHITECTURE.md`, `/agentic-adr` records each binding decision, `/agentic-task` opens trackable work items, `/agentic-audit` flags drift, `/agentic-review <range>` runs a fresh-context review of a diff, `/agentic-design` bootstraps `DESIGN.md` from your tokens (frontend projects), `/agentic-subagent` and `/agentic-skill` scaffold custom subagents and skills. `agentic-philosophy` auto-loads on non-trivial work.
 
-**Revisiting / auditing existing specs.** When specs may have drifted from code, paste:
+**Existing project (brownfield).** Same flow. The project-wide skills (`/agentic-bootstrap`, `/agentic-architecture`) follow a **scan-first pattern**: the agent reads the codebase first, pre-fills every placeholder it can verify, then asks you only about the genuine gaps and conflicts — no philosophical questions, no interview-by-section. The per-artifact skills (`/agentic-adr`, `/agentic-task`, `/agentic-design`, `/agentic-skill`, `/agentic-subagent`) work on a single decision or asset and don't need codebase-wide verification. Backfill ADRs only for decisions that matter going forward.
 
-> *"Read AGENTS.md (or ARCHITECTURE.md). Compare with the current state of the codebase. For every place where the spec disagrees with the code, list the disagreement and suggest whether the spec or the code should change. Do not rewrite the spec yourself — flag and wait."*
+**Revisiting / auditing existing specs.** Run `/agentic-audit` from inside Claude Code or Codex. The skill reads `AGENTS.md`, `ARCHITECTURE.md`, and `doc/adr/` and produces a drift list — one finding per line, format `[file or section]: spec says X, code says Y. Suggested resolution: change spec / change code / discuss.` Read-only — never rewrites specs. Apply judgment manually before changing anything.
 
-Apply judgment manually; don't let the agent rewrite specs unattended.
+**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.
 
-**Project already built with agents.** Treat missing artifacts as brownfield (generate via the relevant prompt) and existing artifacts as audit (run the comparison prompt above).
+**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
+## What ends up in your target project
 
 Only the generated outputs — never templates, prompts, or this guide:
 
 ```
 your-project/
-├── AGENTS.md
+├── AGENTS.md                   (with a managed "Skills installed by agentic" section
+│                                appended below your content if AGENTS.md already existed)
 ├── ARCHITECTURE.md
-├── DESIGN.md                  (optional, UI projects)
+├── DESIGN.md                   (optional, frontend projects)
 ├── doc/
-│   └── adr/
-│       └── NNNN-<title>.md
-└── .claude/
-    ├── skills/<name>/SKILL.md
-    └── agents/<name>.md
+│   ├── adr/
+│   │   └── NNNN-<title>.md
+│   └── tasks/
+│       └── NNNN-<slug>.md
+├── .claude/                    (Claude Code targets)
+│   ├── skills/agentic-*/SKILL.md
+│   └── agents/fresh-context-reviewer.md
+└── .agents/                    (Codex targets, cc-sdd convention)
+    └── skills/agentic-*/{SKILL.md, agents/openai.yaml}
 ```
 
-### Reference table
+The pattern matches how [GitHub's spec-kit](https://github.com/github/spec-kit) and [cookiecutter](https://cookiecutter.readthedocs.io/) handle distribution — templates in one place, outputs in another, never mixed.
+
+## Develop or fork
 
-| Artifact          | Template                                                                                      | Prompt                                              | Lives at                          |
-| ----------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------- |
-| `AGENTS.md`       | [agents-general](templates/agents-general.md) + [agents-project](templates/agents-project.md) | [prompts/agents.md](prompts/agents.md)              | repo root                         |
-| `ARCHITECTURE.md` | [architecture](templates/architecture.md)                                                     | [prompts/architecture.md](prompts/architecture.md)  | repo root                         |
-| ADR               | [adr](templates/adr.md)                                                                       | [prompts/adr.md](prompts/adr.md)                    | `doc/adr/NNNN-<title>.md`         |
-| `DESIGN.md`       | (no template — bootstrap from existing tokens)                                                | [prompts/design.md](prompts/design.md)              | repo root                         |
-| Skill             | [skill](templates/skill.md)                                                                   | [prompts/skill.md](prompts/skill.md)                | `.claude/skills/<name>/SKILL.md`  |
-| Subagent          | [subagent](templates/subagent.md)                                                             | [prompts/subagent.md](prompts/subagent.md)          | `.claude/agents/<name>.md`        |
+Want to contribute, fork, or run the CLI from source?
+
+```bash
+git clone https://github.com/alexandremendoncaalvaro/agentic-development.git
+cd agentic-development
+npm install
+node bin/agentic.js init
+```
 
-Templates carry pure structure. Prompts carry the spec links, conventions, and the literal text to paste.
+Branch layout:
+- `main` — manual workflow source of truth (no CLI code; the npm package gets promoted here when mature).
+- `cli` — CLI development (you're here). Beta releases are published from this branch.
 
 ## License
 

package/WORKFLOW.md

@@ -89,7 +89,7 @@ Cite specific files, not "the codebase." Use just-in-time retrieval: pass paths
 For non-trivial changes, four phases:
 
 1. **Explore (read-only).** Plan mode in your agent. Read, build a mental model, no edits.
-2. **Plan.** Agent writes a Markdown plan. You edit before approving.
+2. **Plan.** Agent writes a Markdown plan. You edit before approving. For non-trivial multi-step work, structure the plan as a per-task file (`doc/tasks/<NNNN>-<slug>.md`) with checkbox acceptance criteria and execution steps — the agent toggles checkboxes as it works rather than rewriting paragraphs, keeping edits cheap and resumable across sessions.
 3. **Implement.** Execute the approved plan; verify each step before moving to the next.
 4. **Commit.** One logical change per commit.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.1.0-beta.1",
+  "version": "0.2.0-beta.1",
   "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
   },
   "scripts": {
     "start": "node bin/agentic.js",
-    "test": "node bin/agentic.js --help && node bin/agentic.js init --help",
+    "test": "node bin/agentic.js --help && node bin/agentic.js init --help && node --test test/*.test.js",
     "prepublishOnly": "npm test"
   },
   "keywords": [
@@ -48,7 +48,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.3.0",
-    "clipboardy": "^5.3.1",
     "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "js-yaml": "^4.1.0"
   }
 }

package/prompts/agents.md

@@ -4,10 +4,18 @@ Open standard: [agents.md](https://agents.md) (Linux Foundation / Agentic AI Fou
 
 ## Paste to your agent
 
-> Read [`templates/agents-general.md`](../templates/agents-general.md) and [`templates/agents-project.md`](../templates/agents-project.md). Interview me one section at a time to fill `agents-project.md`'s placeholders: stack, build/test/lint commands, repo layout (only what's not obvious from the tree), commit conventions, security boundaries, real gotchas you can confirm by reading the code.
+> Read [`templates/agents-project.md`](../templates/agents-project.md). Your job: produce a single `AGENTS.md` at the repo root, ≤150 lines, every line operational. Generic agent behavior (think-before-coding, verify-before-done, etc.) does **not** belong here — that lives in the `agentic-philosophy` skill.
 >
-> **Do not invent values.** When I don't know something, leave `<TODO>` and move on. After the interview, read the codebase to verify what I told you and flag any mismatch.
+> **Step 1 — Scan.** Read `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / equivalent, `README.md`, top-level directories, `doc/` and `doc/adr/` if present, `.claude/` if present, lockfiles, hook configs (`.husky/`, `.pre-commit-config.yaml`, `.github/workflows/`), `git remote -v`. Build a model of stack, entry points, build/test commands, conventions, quality gates, security boundaries, gotchas confirmed by code.
 >
-> Output a single `AGENTS.md` at the repo root: filled `agents-project.md` content first, then `agents-general.md` content appended (drop its H1 — `agents-project.md`'s `# AGENTS.md` owns the merged document).
+> **Step 2 — Pre-fill.** For every `<placeholder>` in [`templates/agents-project.md`](../templates/agents-project.md), fill it from observed signals. No fabrication. If a section has no signal, mark `<TODO: not yet wired>` in one line and move on — do not write meta-prose explaining the gap.
 >
-> Cut every line you can — bloat makes the agent ignore rules.
+> **Step 3 — Show me only the gaps.** Print:
+> - (a) placeholders you could not fill from repo signals;
+> - (b) signals that conflict (e.g. two test commands, two style configs).
+>
+> One question per gap. Skip everything you filled confidently. Do **not** ask philosophical questions ("is this doc primarily for agents or humans?", "what's the most important quality bar?") — those are decisions, not interview material.
+>
+> **Step 4 — On my confirmation, write `AGENTS.md`.** Cut every line that does not change agent behavior. No "External Resources" section (the agent derives URLs from `git remote` / `package.json`). No marketing prose. No appended Universal Agent Behavior block.
+>
+> If something I say contradicts what the code shows, surface the conflict. Don't silently trust me; don't silently trust the code. Flag and wait.

package/prompts/architecture.md

@@ -4,8 +4,18 @@ Pairs with ADRs in `doc/adr/`. Architecture is the binding pattern; ADRs are ind
 
 ## Paste to your agent
 
-> Read [`templates/architecture.md`](../templates/architecture.md). Interview me one section at a time to fill its placeholders: overview, layers and boundaries, patterns (data access, HTTP handlers, async/messaging, errors, validation), naming, observability, deployment topology.
+> Read [`templates/architecture.md`](../templates/architecture.md). Your job: produce `ARCHITECTURE.md` at the repo root.
 >
-> Before writing each section, read the codebase to verify the claim is real. **Do not invent.** Leave `<TODO>` for unknowns.
+> **Step 1 — Scan the code.** Read top-level dirs, the main entry points (servers, CLI, jobs), boundary code (handlers, repos, gateways, middleware), config and env loading, observability hooks, deploy config (`Dockerfile`, `compose.yml`, `k8s/`, `terraform/`, GitHub Actions). Existing ADRs in `doc/adr/` are binding — read them all.
 >
-> Output `ARCHITECTURE.md` at the repo root. At the end, list any decision that should become an ADR — don't write them yet, just flag.
+> **Step 2 — Pre-fill.** For each placeholder, fill from what the code actually does: layers and boundaries, data access pattern, HTTP middleware chain, async/messaging, error and validation patterns, naming, logging/metrics/tracing, deployment topology. No fabrication.
+>
+> **Step 3 — Show me only the gaps.** Print:
+> - (a) placeholders without a code signal;
+> - (b) places where the code shows two competing patterns (e.g. some handlers go through middleware, some don't).
+>
+> One question per gap.
+>
+> **Step 4 — On my confirmation, write the file.** Cut every line that does not lock a binding pattern. At the end, list any decision that should become an ADR — flag, do not write the ADR yet.
+>
+> If something I say contradicts what the code shows, surface the conflict. Don't silently trust me; don't silently trust the code.

package/prompts/task.md

@@ -0,0 +1,26 @@
+# Bootstrap a Task
+
+A per-task tracking file optimized for LLM editing: status changes via single checkbox toggles, append-only Notes log, no rewrites of large blocks.
+
+## Where it lives
+
+`doc/tasks/<NNNN>-<short-slug>.md` — sequential numbering, kebab-case slug, mirrors the ADR convention (`doc/adr/`).
+
+## Why this format
+
+Toggling a checkbox is a single-character `Edit` operation. Rewriting a paragraph is risky and expensive in tokens. Markdown checklists make the LLM's edits cheap, reviewable, and idempotent. Pattern documented in [spec-kit's tasks.md](https://github.com/github/spec-kit/blob/main/templates/commands/tasks.md), [taskmd](https://medium.com/@driangle/taskmd-task-management-for-the-ai-era-92d8b476e24e), [Backlog.md](https://github.com/MrLesk/Backlog.md), and [Claude Code's Tasks API](https://platform.claude.com/docs/en/agent-sdk/todo-tracking).
+
+## Paste to your agent
+
+> Use [`templates/task.md`](../templates/task.md) to draft `doc/tasks/<NNNN>-<short-slug>.md` (next available number) for the task: `<one-line task description>`.
+>
+> Interview me to fill:
+> - Context: why this task, what problem it solves
+> - Acceptance Criteria: measurable conditions per [WORKFLOW.md §1](../WORKFLOW.md), each as 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 as a checkbox
+>
+> Status starts at `proposed`. Created: today. Owner: ask me. Board ref: leave blank unless I provide one. Leave Notes empty (it gets filled during execution). Definition of Done section stays as in the template.
+>
+> **Do not invent values.** When I don't know something, leave `<TODO>` and ask. Stop after writing the file. Wait for me to start work.
+>
+> When working on the task later, edit the file by toggling checkboxes (`- [ ]` → `- [x]`) and appending to Notes — never rewrite existing sections.