@alexandrealvaro/agentic 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Alvaro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# Agentic Development
+
+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).
+
+## 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).
+
+## What's here
+
+- **[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:
+
+```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.
+
+> **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.
+
+### Manual workflow
+
+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.
+
+#### Setup (once)
+
+1. Read [`WORKFLOW.md`](WORKFLOW.md) — the philosophy that everything else follows from.
+2. Clone this repo to a location outside your projects:
+
+   ```bash
+   git clone https://github.com/alexandremendoncaalvaro/agentic-development.git ~/dev/agentic-development
+   ```
+
+   **Never copy this kit into your target project.** Only the generated artifacts go there.
+
+#### Give the agent access to templates
+
+When you paste a prompt from `prompts/`, the agent needs to read the matching template in `templates/`. Two ways to grant access:
+
+- **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.
+
+#### Workflows by scenario
+
+**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.
+
+**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.
+
+**Revisiting / auditing existing specs.** When specs may have drifted from code, paste:
+
+> *"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."*
+
+Apply judgment manually; don't let the agent rewrite specs unattended.
+
+**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).
+
+#### What ends up in your target project
+
+Only the generated outputs — never templates, prompts, or this guide:
+
+```
+your-project/
+├── AGENTS.md
+├── ARCHITECTURE.md
+├── DESIGN.md                  (optional, UI projects)
+├── doc/
+│   └── adr/
+│       └── NNNN-<title>.md
+└── .claude/
+    ├── skills/<name>/SKILL.md
+    └── agents/<name>.md
+```
+
+### Reference table
+
+| 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`        |
+
+Templates carry pure structure. Prompts carry the spec links, conventions, and the literal text to paste.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/WORKFLOW.md

@@ -0,0 +1,209 @@
+# Pragmatic Workflow: Engineering with LLMs
+
+Engineering production code with LLMs. Agentic, not vibe coding.
+
+**The principle behind the rest:** context engineering beats prompt engineering. Context is finite and decays as it fills — aim for the smallest set of high-signal tokens that gets the outcome.
+
+## TL;DR
+
+Agents do not replace engineering. They speed up execution, but they make specification, context, validation, and review *more* important than before.
+
+What to keep in mind:
+
+1. **Context is the product.** The agent performs only as well as the context you give it. Small, clear, relevant context beats large, noisy context.
+2. **Spec before code.** Define rules, constraints, architecture, acceptance criteria, and expected output before any implementation.
+3. **Docs are for *why*, code for *what*.** History lives in git. Comments justify non-obvious choices, never restate the line.
+4. **Real examples beat generic instructions.** "Follow this existing file" lands harder than "follow best practices."
+5. **Always know the canonical path.** If you deviate, do it deliberately — never by forgetting the happy path exists.
+6. **Outcome before path.** Give the finish line — raw input plus exact expected output — and let the agent build the algorithm to connect them.
+7. **Pin load-bearing architectural decisions.** The agent will invent what isn't specified. Lock architecture into `AGENTS.md`.
+8. **A good prompt has a stop condition.** Say what to do, what not to do, and where to stop.
+9. **Plan before execution.** For non-trivial work: explore, plan, review the plan, implement, verify.
+10. **Format helps, but does not save bad thinking.** Markdown, XML, YAML, and JSON only reduce ambiguity. They don't replace clarity.
+11. **The bottleneck is judgment, not generation.** Agents generate fast; the hard part is catching what's almost right but wrong.
+12. **Review needs distance.** The context that produced a solution tends to defend it. Review with a fresh context — diff plus spec, no history.
+13. **Automation needs rails.** Hooks, tests, lint, CI, sandboxing, and permissions matter more than advisory text the agent can forget.
+14. **Autonomy requires observability.** If the agent makes decisions, log the trajectory: tool calls, intermediate outputs, failures.
+15. **Staged spikes when the technique is uncertain.** When the *how* is unknown — a library choice, a CV technique, a multi-stage transformation — break the problem into staged spikes against golden fixtures with per-stage debug artifacts.
+
+> Working with agents means trading typing for technical direction. The value is in giving the right context, setting boundaries, validating the result, and keeping "almost right" out of production.
+
+## 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.
+
+**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` (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.
+
+**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 three:
+
+- **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.
+
+## 2. Docs vs. Code
+
+Avoid putting implementation code in docs unless it's executable, generated, or a minimal API/contract surface. Docs define intent, constraints, contracts, and decisions; production logic lives in code.
+
+The split is simple. **Docs are for the *why*** — decisions, not history. Git tracks history; docs explain the reasoning that won't survive otherwise. **Code is for the *what*** — clean naming and small units make logic self-evident, and the more your code does this work, the less your docs need to.
+
+Comments are exceptions. They justify *why* a non-obvious choice was made — never *what* the line does. No commented-out code, and no orphan `TODO` or `FIXME`: every deferred item references an issue, ADR, or explicit follow-up.
+
+## 3. Format by Evidence
+
+Structure reduces ambiguity, but format isn't magic. Pick the right one for the surface:
+
+- **Markdown** for repo files (`AGENTS.md`, `CLAUDE.md`, `SKILL.md`, specs, ADRs). Readable, diffable, agent-friendly.
+- **XML-style tags** inside prompts when boundaries matter: `<instructions>`, `<context>`, `<examples>`, `<input>`, `<constraints>`, `<output_format>`.
+- **YAML** for metadata, frontmatter, and declarative config.
+- **JSON or schema** for machine-validated output.
+
+Use XML when the prompt mixes instructions, retrieved context, examples, user input, and expected output — the separation pays off when there's noise to fight. Skip it for simple prompts; if Markdown headings or plain text are clear enough, use them.
+
+No format is universally best. **An observation from my practice, not benchmarked:** I've seen consistent gains when shifting prompts to XML — most noticeably with autonomous agents, where the prompt has to land alone without conversational refinement. Direct interactive use (Claude Code, Codex) tolerates loose Markdown; unattended agents don't. Claude in particular seems to respond well to XML, which I attribute to its training, but I haven't benchmarked it. Treat this as a starting hypothesis worth testing on your own target model and task before standardizing.
+
+## 4. Find the Happy Path
+
+Before implementing, ask:
+
+> *"What is the canonical, idiomatic way to implement [X] in [stack]? Cite official docs. List common deviations and why people take them."*
+
+Then check continuously, especially mid-implementation:
+
+> *"We are at step Y. Are we still on the happy path? If we deviated, was it deliberate?"*
+
+Sometimes you can't follow the happy path — that's fine. But always know where it is and why you left it.
+
+## 5. Ground in Real Patterns
+
+Don't dump the codebase into context. Anchor the model in a specific, project-relevant example.
+
+> *"Find an existing example of [similar feature]; use that exact structure."*
+
+Cite specific files, not "the codebase." Use just-in-time retrieval: pass paths or IDs and let the agent fetch via tools when it needs to read them.
+
+## 6. Explore → Plan → Implement → Commit
+
+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.
+3. **Implement.** Execute the approved plan; verify each step before moving to the next.
+4. **Commit.** One logical change per commit.
+
+Skip this for diffs you can describe in one sentence.
+
+## 7. Action Commands With Stop Criteria
+
+Leave no room for interpretation. Tell the model where to stop.
+
+- **Avoid:** *"Here is the data. What do you think?"*
+- **Prefer:** *"Analyze this data. List the top 3 bottlenecks. Stop there — don't propose fixes unless I ask."*
+
+The stop criterion is as important as the action. Without it, the agent generalizes outward and you end up trimming output you didn't ask for.
+
+## 8. Architectural Boundaries
+
+Lock the load-bearing decisions into `AGENTS.md` or `CLAUDE.md` so the agent doesn't relitigate them every session:
+
+> "Apply: **Clean Architecture** — isolate core logic from frameworks. **Small units** — single-responsibility, low indentation, no `else` chains. **Modular and testable** — no over-engineering."
+
+The agent will follow what's specified and invent what isn't. Prefer specifying.
+
+## 9. Outcome-Based Prompting (TDG)
+
+Give the finish line first, not the path:
+
+1. **Ground truth.** Raw input plus exact expected output.
+2. **Command the implementation.** The algorithm that connects the two.
+3. **Iterate by criterion.** Ask for three approaches; pick by *one* explicit criterion (readability, performance, *or* testability — not all three at once).
+4. **Test Dependency Map, not procedural TDD.** Don't tell the agent "do TDD" — tell it *which* tests cover the file. *"Before modifying X.ts, list which tests cover it. Run. Modify. Run. If none cover it, write one first."*
+
+## 10. Reviewer With Fresh Context
+
+The agent that wrote the code is biased about it. The same reasoning that produced the solution defends the solution.
+
+> *"Open a fresh agent with no history. Give it only the diff and the spec. Review as a strict Senior reviewing a Junior PR. Be ruthless about bugs, coupling, edge cases."*
+
+In Claude Code, this means a subagent (the `Task` tool, or a custom `.claude/agents/*.md` file). Without that infrastructure: `/clear`, new context, paste diff plus spec.
+
+## 11. Quality Gates: Determinism Over Persuasion
+
+`AGENTS.md` is advisory. Hooks and CI are deterministic. The difference matters: text you write hoping the agent obeys is not the same as a script that exits non-zero when a rule is violated.
+
+- **Hooks for inviolable rules** (formatter, secret-scan, lint). Not text the agent might forget.
+- **Pre-commit fast** (lint, format, secrets); **pre-push thorough** (build, unit tests, integration tests). Slow pre-commits push devs to `--no-verify`.
+- **Visual or E2E for UI.** Type-check confirms the code compiles, not that the feature works. Open the browser (Claude in Chrome, DevTools MCP).
+- **Sandboxing plus scoped permissions** for autonomy: allowlists, OS sandbox, classifier-reviewed auto mode. The bigger the autonomy, the more rails you need.
+- **Never bypass.** No `--no-verify`. Failing tests means not ready.
+
+## 12. The Bottleneck Is Discrimination, Not Generation
+
+Modern agents handle most routine implementation. The work has shifted to catching what they got wrong.
+
+Two 2025 industry surveys point at the same wall. JetBrains' DevEcosystem 2025 reports that only **44%** of developers have AI fully or partially integrated into their workflow. Stack Overflow's 2025 Developer Survey adds: **66%** of developers cite "AI solutions that are almost right, but not quite" as their top frustration, and **45%** say debugging AI-generated code is more time-consuming.
+
+The takeaway: §10 (Reviewer) and §11 (Quality Gates) are not optional. Skipping them is where bug density grows.
+
+## 13. Evals for Anything Autonomous
+
+If your agent is making decisions on its own, you need evals. A few principles:
+
+- **Trajectory beats final output.** Output-only eval hides failures in tool calls, retrieval, and intermediate decisions that the final answer can mask. Log tool calls and intermediate states.
+- **Observability before evals.** Get traces first; build the eval suite on top.
+- **LLM-as-judge for breadth, humans for depth.**
+- **The unit under test is prompt + scaffold + model.** Changing any of the three is a release.
+
+## 14. Staged Spikes With Golden Fixtures
+
+Sometimes the spec is clear but the *technique* is uncertain — you don't know which library, which CV approach, which decomposition. Don't ask the agent to solve it end-to-end. Break the problem into staged spikes and validate each one against curated ground truth.
+
+The flow has four parts:
+
+1. **Discovery first.** Ask the agent to list canonical approaches grounded in official docs and real examples. Pick one by an explicit criterion. The output of this step is information, not code.
+2. **Golden fixture.** Curate inputs with rich expected outputs. For computer vision, that means bounding boxes, sizes, lighting, difficulty tags, edge cases — not just "three circles." Keep the fixture as JSON keyed by input path.
+3. **Pipeline with gates.** One technique per stage; each gate emits a debug artifact: an image to `debug/01-preprocess/`, intermediate JSON, a log row — whatever makes the stage's output inspectable.
+4. **Two layers of evaluation.** End-to-end against the fixture, *and* per-stage debug to locate where things diverged when it failed.
+
+**Why this beats end-to-end:** §9 (TDG) assumes the path is known. When you don't know it, end-to-end evaluation tells you *that* it failed, not *where*. Stage-level artifacts make the divergence inspectable, so you fix the right gate instead of guessing at the final output.
+
+**When to use it:** the unknown is *how* — a library choice, a CV technique, a multi-stage transformation. Skip it when the *how* is routine.
+
+This is a combination of established practices, not new terminology: spike (XP), golden datasets, stage-segmented error analysis, trajectory evaluation, and visual debugging in CV pipelines.
+
+---
+
+These are starting points. Prune what doesn't fit your codebase.
+
+## How this guide was built
+
+This is not theory I read and copied. Most of the practices here come from years of shipping production code, with and without LLMs.
+
+**Patterns I was already using when I drafted this guide.** Several of them I used before knowing they had established names; once the industry converged on a label, I adopted it to make the conversation easier: **Spec-Driven Design** (§1), **Docs-vs-Code separation** (§2), **pattern matching by real examples** (§5), **explicit Action Commands** (§7), **Architectural Boundaries** (§8), **Outcome-Based Prompting / TDG** (§9), the **senior-reviewer technique** (§10), and **deterministic Quality Gates** (§11).
+
+**The XML observation in §3** is also drawn from practice, not benchmarks. It's a hypothesis worth testing on your own setup, not a settled finding.
+
+**Practices that came in through iteration on this guide.** They weren't in my original draft, but each matches a problem I'd already encountered or a habit I'd only formalized loosely: **Find the Happy Path** (§4), **Explore → Plan → Implement → Commit** (§6), **The Bottleneck Is Discrimination, Not Generation** (§12 — the 2025 industry statistics ground the principle, they didn't generate it), and **Evals for Anything Autonomous** (§13).
+
+**§14 (Staged Spikes With Golden Fixtures) is my own working technique.** I haven't seen it documented end-to-end as a single named pattern, but each component (spike, golden dataset, stage-segmented error analysis, trajectory evaluation, visual CV debugging) has its own lineage in the literature listed under Sources. The combination — discovery → fixture → staged pipeline with debug artifacts → two-layer evaluation — is how I attack problems where the *technique* itself is uncertain.
+
+External claims (specific percentages, named frameworks) are cited under Sources. Everything else is operational guidance from practice or synthesis across that material — a working model, refined over time, not academic claim.
+
+## Sources
+
+**§1 — Spec-Driven Design**
+- DESIGN.md spec (Google Labs): https://github.com/google-labs-code/design.md
+- SKILL.md spec (Anthropic): https://code.claude.com/docs/en/skills
+
+**§12 — The Bottleneck Is Discrimination, Not Generation**
+- JetBrains *DevEcosystem 2025*: https://devecosystem-2025.jetbrains.com/artificial-intelligence
+- Stack Overflow *2025 Developer Survey* (AI section): https://survey.stackoverflow.co/2025/ai
+
+**§14 — Staged Spikes With Golden Fixtures**
+- Spike (XP) — Wikipedia: https://en.wikipedia.org/wiki/Spike_(software_development)
+- Golden datasets — Arize: https://arize.com/resource/golden-dataset/
+- Stage-segmented error analysis — Hamel Husain's evals FAQ: https://hamel.dev/blog/posts/evals-faq/
+- Trajectory evaluation — LangSmith docs: https://docs.langchain.com/langsmith/trajectory-evals
+- Visual CV debugging — OpenCV cvv tutorial: https://docs.opencv.org/3.4/d7/dcf/tutorial_cvv_introduction.html

package/bin/agentic.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+
+run(process.argv).catch((err) => {
+  console.error(`agentic: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@alexandrealvaro/agentic",
+  "version": "0.1.0-beta.1",
+  "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
+  "type": "module",
+  "bin": {
+    "agentic": "./bin/agentic.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "prompts/",
+    "WORKFLOW.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/agentic.js",
+    "test": "node bin/agentic.js --help && node bin/agentic.js init --help",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "llm",
+    "agents",
+    "agentic",
+    "spec-driven",
+    "scaffolding",
+    "ai",
+    "claude-code",
+    "agents-md"
+  ],
+  "license": "MIT",
+  "author": "Alexandre Alvaro <alexandre.alvaro@hotmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexandremendoncaalvaro/agentic-development.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alexandremendoncaalvaro/agentic-development/issues"
+  },
+  "homepage": "https://github.com/alexandremendoncaalvaro/agentic-development#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.3.0",
+    "clipboardy": "^5.3.1",
+    "commander": "^12.1.0"
+  }
+}

package/prompts/adr.md

@@ -0,0 +1,7 @@
+# Bootstrap an ADR
+
+Format: Michael Nygard's pattern (Context, Decision, Consequences, Alternatives). Status lifecycle: `proposed` → `accepted` → `deprecated` | `superseded by ADR-NNNN`.
+
+## Paste to your agent
+
+> Use [`templates/adr.md`](../templates/adr.md) to draft `doc/adr/<NNNN>-<short-title>.md` (next available number) for the decision: `<one-line decision>`. Status `proposed`, today's date. Fill Context, Decision, Consequences, and Alternatives Considered from our conversation only — don't invent. Stop after writing the file. Wait for review before changing status to `accepted`.

package/prompts/agents.md

@@ -0,0 +1,13 @@
+# Bootstrap AGENTS.md
+
+Open standard: [agents.md](https://agents.md) (Linux Foundation / Agentic AI Foundation). Claude Code reads `CLAUDE.md`; mirror or import via `@AGENTS.md`.
+
+## 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.
+>
+> **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.
+>
+> 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).
+>
+> Cut every line you can — bloat makes the agent ignore rules.

package/prompts/architecture.md

@@ -0,0 +1,11 @@
+# Bootstrap ARCHITECTURE.md
+
+Pairs with ADRs in `doc/adr/`. Architecture is the binding pattern; ADRs are individual decisions with status.
+
+## 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.
+>
+> Before writing each section, read the codebase to verify the claim is real. **Do not invent.** Leave `<TODO>` for unknowns.
+>
+> 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.

package/prompts/design.md

@@ -0,0 +1,19 @@
+# Bootstrap DESIGN.md
+
+Spec: [github.com/google-labs-code/design.md](https://github.com/google-labs-code/design.md) (Apache 2.0). Format: YAML frontmatter (W3C-compatible `$value`/`$type` tokens) + Markdown body (rationale, do's/don'ts).
+
+Canonical sections: `Overview`, `Colors`, `Typography`, `Layout`, `Elevation & Depth`, `Shapes`, `Components`, `Do's and Don'ts`. **Add `Motion`** (easings, durations) — not in the official spec yet.
+
+There is no template — bootstrap from existing tokens.
+
+## Workflow
+
+1. **Retrieval** — point the agent at the source: Figma file, `tailwind.config.js`, `tokens.json`, design system docs, or stylesheet.
+2. **Extraction** — agent extracts tokens (colors, typography, spacing, radii, shadows, motion) into YAML frontmatter.
+3. **Synthesis** — agent writes the Markdown body: rationale per token group, application rules, do's/don'ts. Cite the source.
+4. **Validation** — `npx @google/design.md lint DESIGN.md`. Fix errors before shipping.
+5. **Component mapping** — if you use Figma, set up Code Connect to map each Figma component to its code component. Without this, the agent guesses.
+
+## Paste to your agent
+
+> Read the DESIGN.md spec at https://github.com/google-labs-code/design.md. Extract tokens from `<source: Figma URL / tailwind.config.js / tokens.json / stylesheet>`. Generate `DESIGN.md` at the repo root with YAML frontmatter (W3C-compliant `$value`/`$type`) + Markdown body explaining rationale and application rules per token group. Add a `## Motion` section if any easings/durations are defined. Validate with `npx @google/design.md lint`. **Do not invent tokens not in the source** — if a category is missing, leave the section with a `<TODO>` note.

package/prompts/skill.md

@@ -0,0 +1,21 @@
+# Bootstrap a Skill
+
+Spec: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) | open standard [agentskills.io](https://agentskills.io) | examples [github.com/anthropics/skills](https://github.com/anthropics/skills)
+
+## Where it lives
+
+- Personal: `~/.claude/skills/<skill-name>/SKILL.md`
+- Project: `.claude/skills/<skill-name>/SKILL.md`
+
+Directory name becomes the command (`/<skill-name>`).
+
+## Paste to your agent
+
+> Read the SKILL spec at https://code.claude.com/docs/en/skills and the structure in [`templates/skill.md`](../templates/skill.md). Create a skill at `<.claude/skills/<name>/SKILL.md | ~/.claude/skills/<name>/SKILL.md>` that `<does X when Y>`.
+>
+> Constraints:
+> - `description` is the triggering signal — include keywords a user would naturally say. Combined `description` + `when_to_use` is capped at 1,536 chars.
+> - Body ≤500 lines; move long material to sibling files (`reference.md`, `examples.md`, `scripts/`).
+> - Body stays in context after invocation — every line is recurring token cost. State *what to do*, not narration.
+> - Don't restate AGENTS.md.
+> - Only declare frontmatter fields you actually need. **Do not invent fields not in the spec.**

package/prompts/subagent.md

@@ -0,0 +1,34 @@
+# Bootstrap a Subagent
+
+Spec: [code.claude.com/docs/en/sub-agents](https://code.claude.com/docs/en/sub-agents)
+
+A custom Claude Code subagent runs with isolated context, scoped tools, and its own system prompt. The body of the file becomes the subagent's full system prompt — it does **not** inherit AGENTS.md / CLAUDE.md from the parent.
+
+## Where it lives
+
+- Project (versioned): `.claude/agents/<name>.md`
+- Personal: `~/.claude/agents/<name>.md`
+
+Edits to files on disk require a session restart; agents created via `/agents` take effect immediately.
+
+## Common patterns
+
+| Pattern                | Tools                       | Model      | Notes                                                   |
+| ---------------------- | --------------------------- | ---------- | ------------------------------------------------------- |
+| Fresh-context reviewer | `Read, Glob, Grep, Bash`    | `sonnet`   | Matches WORKFLOW §10. No write tools.                   |
+| Codebase researcher    | use built-in **Explore**    | inherit    | Don't build custom unless you need different tools.     |
+| Diff-only auditor      | `Read, Bash`                | `sonnet`   | Pair with `permissionMode: dontAsk` for read-only runs. |
+
+Built-in subagents (`Explore`, `Plan`, `general-purpose`) cover most cases. Build a custom one only when you need a specific role, scoped tools, persistent memory, or a different model.
+
+## Paste to your agent
+
+> Read the subagents spec at https://code.claude.com/docs/en/sub-agents and the structure in [`templates/subagent.md`](../templates/subagent.md). Create a project subagent at `.claude/agents/<name>.md` for `<role and trigger>`.
+>
+> Constraints:
+> - `description` is the routing signal — Claude reads it to decide whether to delegate. Be specific.
+> - Body = full system prompt; every line costs tokens on every subagent turn. Be terse.
+> - Don't restate AGENTS.md. Subagents don't read it. State only what differs.
+> - Limit tools deliberately. A reviewer with `Write` access stops being a reviewer.
+> - Tell the subagent where to stop.
+> - Frontmatter: `name`, `description`, plus only the fields you actually need from the spec. **Do not invent fields not in the spec.**

package/src/commands/init.js

@@ -0,0 +1,108 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import * as p from '@clack/prompts';
+import clipboard from 'clipboardy';
+import { detectMode } from '../lib/detect.js';
+import { renderAgentsBootstrap } from '../lib/render.js';
+
+const VALID_MODES = ['auto', 'greenfield', 'brownfield', 'audit'];
+
+const MODE_LABEL = {
+  greenfield: 'greenfield — empty project',
+  brownfield: 'brownfield — existing code, no AGENTS.md',
+  audit: 'audit — AGENTS.md exists, compare drift',
+};
+
+export async function initCommand(opts) {
+  if (!VALID_MODES.includes(opts.mode)) {
+    throw new Error(
+      `invalid mode "${opts.mode}". Use one of: ${VALID_MODES.join(', ')}`
+    );
+  }
+
+  const flagDest = opts.copy
+    ? 'clipboard'
+    : opts.out
+      ? 'file'
+      : opts.stdout
+        ? 'stdout'
+        : null;
+  const interactive = process.stdout.isTTY && flagDest === null;
+
+  const detected = detectMode(process.cwd());
+  let mode = opts.mode === 'auto' ? detected : opts.mode;
+  let dest = flagDest ?? 'stdout';
+  let outPath = opts.out ?? null;
+
+  if (interactive) {
+    p.intro('agentic init');
+    p.note(MODE_LABEL[detected], 'Detected context');
+
+    if (opts.mode === 'auto') {
+      const choice = await p.select({
+        message: 'Confirm mode?',
+        options: [
+          { value: detected, label: `Use detected (${detected})` },
+          ...['greenfield', 'brownfield', 'audit']
+            .filter((m) => m !== detected)
+            .map((m) => ({ value: m, label: `Override → ${MODE_LABEL[m]}` })),
+        ],
+      });
+      if (p.isCancel(choice)) {
+        p.cancel('Cancelled.');
+        return;
+      }
+      mode = choice;
+    }
+
+    const chosen = await p.select({
+      message: 'Where to send the prompt?',
+      options: [
+        { value: 'clipboard', label: 'Copy to clipboard', hint: 'recommended' },
+        { value: 'stdout', label: 'Print to stdout', hint: 'for piping' },
+        { value: 'file', label: 'Save to file' },
+      ],
+    });
+    if (p.isCancel(chosen)) {
+      p.cancel('Cancelled.');
+      return;
+    }
+    dest = chosen;
+
+    if (dest === 'file') {
+      const path = await p.text({
+        message: 'File path',
+        initialValue: './agentic-init-prompt.md',
+      });
+      if (p.isCancel(path)) {
+        p.cancel('Cancelled.');
+        return;
+      }
+      outPath = path;
+    }
+  }
+
+  const prompt = renderAgentsBootstrap({ mode });
+
+  if (dest === 'clipboard') {
+    await clipboard.write(prompt);
+    if (interactive) {
+      p.outro('Copied to clipboard. Paste it into Claude Code, Codex, or any agentic tool.');
+    } else {
+      process.stderr.write('Copied to clipboard.\n');
+    }
+  } else if (dest === 'file') {
+    const absPath = resolve(outPath);
+    writeFileSync(absPath, prompt);
+    if (interactive) {
+      p.outro(`Saved to ${absPath}. Open it and paste into your agent.`);
+    } else {
+      process.stderr.write(`Saved to ${absPath}\n`);
+    }
+  } else {
+    if (interactive) {
+      p.outro('Prompt below — copy and paste into your agent.');
+    }
+    process.stdout.write(prompt);
+  }
+}

package/src/index.js

@@ -0,0 +1,30 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { initCommand } from './commands/init.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, '..', 'package.json'), 'utf8')
+);
+
+export async function run(argv) {
+  const program = new Command();
+
+  program
+    .name('agentic')
+    .description(pkg.description)
+    .version(pkg.version);
+
+  program
+    .command('init')
+    .description('Bootstrap AGENTS.md for the current project — interactive by default')
+    .option('-m, --mode <mode>', 'force mode: auto | greenfield | brownfield | audit', 'auto')
+    .option('--copy', 'skip TUI and copy the prompt to clipboard')
+    .option('--stdout', 'skip TUI and print the prompt to stdout')
+    .option('-o, --out <file>', 'skip TUI and write the prompt to a file')
+    .action(initCommand);
+
+  await program.parseAsync(argv);
+}

package/src/lib/detect.js

@@ -0,0 +1,36 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TRIVIAL_ENTRIES = new Set([
+  '.git',
+  'node_modules',
+  '.DS_Store',
+  '.idea',
+  '.vscode',
+  '.gitignore',
+  '.gitattributes',
+  '.env',
+  '.env.local',
+  '.env.example',
+  'README.md',
+  'LICENSE',
+  'LICENSE.md',
+]);
+
+/**
+ * Detect the project's current state to pick a default mode for `init`.
+ * - audit: AGENTS.md already exists; compare against the codebase
+ * - greenfield: only trivial files (no real code yet)
+ * - brownfield: has code but no AGENTS.md
+ */
+export function detectMode(dir) {
+  if (existsSync(join(dir, 'AGENTS.md'))) {
+    return 'audit';
+  }
+
+  const meaningful = readdirSync(dir).filter(
+    (name) => !TRIVIAL_ENTRIES.has(name) && !name.startsWith('.')
+  );
+
+  return meaningful.length === 0 ? 'greenfield' : 'brownfield';
+}

package/src/lib/render.js

@@ -0,0 +1,66 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = join(__dirname, '..', '..');
+
+function readKit(relativePath) {
+  return readFileSync(join(KIT_ROOT, relativePath), 'utf8');
+}
+
+const MODE_CONTEXT = {
+  greenfield:
+    "Empty project. Interview me from scratch — there's no existing code yet to verify against.",
+  brownfield:
+    'Existing codebase, no AGENTS.md yet. After interviewing me, read the actual code to verify what I told you and flag any mismatch before writing anything.',
+  audit:
+    "AGENTS.md already exists. Do not rewrite it. Compare it against the current codebase and against the template structure below. List every drift, then wait — I'll decide what to change.",
+};
+
+export function renderAgentsBootstrap({ mode }) {
+  const general = readKit('templates/agents-general.md').trim();
+  const project = readKit('templates/agents-project.md').trim();
+
+  const outputInstruction =
+    mode === 'audit'
+      ? 'Output: a list of disagreements. Format each as `[file or section]: spec says X, code says Y. Suggested resolution: [change spec / change code / discuss].`'
+      : "Output: a single `AGENTS.md` at the repo root — filled `agents-project.md` content first, then `agents-general.md` content appended. Drop `agents-general.md`'s H1; `agents-project.md`'s `# AGENTS.md` owns the merged document.";
+
+  return `# Bootstrap AGENTS.md  (mode: ${mode})
+
+Paste this entire output into your agent. Both templates are inlined below — no \`--add-dir\` needed.
+
+---
+
+## Mode context
+
+${MODE_CONTEXT[mode]}
+
+---
+
+## Template: agents-general.md (universal agent behavior)
+
+${general}
+
+---
+
+## Template: agents-project.md (per-project structure with placeholders)
+
+${project}
+
+---
+
+## Instructions
+
+> Read both templates above.
+>
+> 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), commit conventions, security boundaries, and real gotchas you can confirm by reading the code.
+>
+> **Do not invent values.** When I don't know something, leave \`<TODO>\` and move on.
+>
+> ${outputInstruction}
+>
+> Cut every line you can — bloat makes the agent ignore rules.
+`;
+}

package/templates/adr.md

@@ -0,0 +1,22 @@
+# ADR-NNNN: `<short imperative title>`
+
+**Status:** `<proposed | accepted | deprecated | superseded by ADR-NNNN>`
+**Date:** `<YYYY-MM-DD>`
+**Deciders:** `<names or roles>`
+
+## Context
+
+`<What is the issue motivating this decision? What forces are at play — technical, organizational, regulatory, cost?>`
+
+## Decision
+
+`<State as a directive: "We will…". One decision per ADR.>`
+
+## Consequences
+
+`<What becomes easier, harder, or different. List positive, negative, and neutral consequences.>`
+
+## Alternatives Considered
+
+* `<option>` — `<why rejected>`
+* `<option>` — `<why rejected>`

package/templates/agents-general.md

@@ -0,0 +1,82 @@
+# Universal Agent Behavior
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## Ground Before Coding
+
+**Anchor in real patterns. Research the canonical path.**
+
+- Find the canonical/idiomatic way to do it. Note where you deviate and why.
+- Find an existing example in the codebase; reuse its structure.
+- Cite specific files, not "the codebase". Fetch via tools — don't dump code into context.
+- For non-trivial changes, explore (read-only) → plan → implement → commit. Skip for diffs you can describe in one sentence.
+
+## Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- Comments justify *why* a non-obvious choice was made, not *what* the line does. No commented-out code; no orphan `TODO`/`FIXME` — every deferred item references an issue, ADR, or follow-up.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+Before modifying a file, list which tests cover it. Run. Modify. Run. If none, write one first.
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## Verify Before Claiming Done
+
+- Type-check and tests verify *code*, not *feature*.
+- For UI/runtime changes, exercise the feature in a browser.
+- Can't verify it? Say so. Don't claim success.
+- Never bypass gates (`--no-verify`, skipped hooks, deleted failing tests).
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

package/templates/agents-project.md

@@ -0,0 +1,91 @@
+# AGENTS.md
+
+## Project Overview
+
+`<what this project does, who uses it, the quality bar that matters most>`
+
+**Stack:** `<languages, runtimes, frameworks, database>`
+**Entry points:** `<main services and where to find them>`
+
+## Setup, Build, Test
+
+```bash
+# Install
+<command>
+
+# Build
+<command>
+
+# Test (single file preferred over full suite)
+<single test command>
+<full suite command>
+
+# Run before any commit
+<lint>
+<format>
+<typecheck>
+```
+
+Document non-obvious flags or env vars inline.
+
+## Quality Gates
+
+Deterministic enforcement — agent cannot skip.
+
+* Pre-commit hook (fast): `<lint, format, secret-scan>`
+* Pre-push hook (thorough): `<build + unit + integration>`
+* Visual/E2E for UI (if applicable): `<e.g., Cypress, Playwright, Claude in Chrome — leave blank for non-UI projects>`
+* Hook config lives in: `<.husky/, .pre-commit-config.yaml, .claude/settings.json — see code.claude.com/docs/en/hooks>`
+* CI blocks on: `<list>`
+
+## Code Style
+
+Only what differs from language defaults.
+
+* `<e.g., ES modules, not CommonJS>`
+* `<e.g., destructure imports>`
+* `<e.g., no `any` outside `internal/types/`>`
+* `<e.g., Pydantic for all request/response shapes>`
+
+## Architectural Principles
+
+Decisions the agent must follow, not reinvent.
+
+* `<e.g., Clean Architecture — core logic isolated from frameworks>`
+* `<e.g., Repository pattern for all DB access>`
+* `<e.g., All HTTP handlers go through middleware in `src/middleware/`>`
+* `<e.g., Single responsibility, no `else` chains, low indentation>`
+
+## Repository Layout
+
+`<where logic, tests, docs, infra live — only if not obvious from the tree>`
+`<.claude/skills/ — list of available skills, if any>`
+`<.claude/agents/ — list of custom subagents, if any>`
+
+## Commit & PR Conventions
+
+* Commits: `<conventional / project-specific>`
+* Branches: `<feat/, fix/, chore/>`
+* PRs require: `<green CI, one review, linked issue>`
+* Never push to `<main>` directly.
+
+## Security & Privacy
+
+* Secrets: `<location — never committed>`
+* Files the agent must not read or modify: `<list>`
+* Data classification: `<e.g., no PII in logs>`
+* Pre-approved commands (no prompt): `<e.g., gh, npm test, npm run lint>`
+* MCP servers approved: `<list>`
+
+## Gotchas
+
+Real traps. Each one should map to an incident.
+
+* `<e.g., migrations not idempotent — never edit, always create new>`
+* `<e.g., DB is UTC, app displays America/Sao_Paulo>`
+
+## External Resources
+
+* Docs: `<URL>`
+* Issues: `<URL>`
+* Runbook: `<URL>`

package/templates/architecture.md

@@ -0,0 +1,40 @@
+# Architecture
+
+System-level patterns and boundaries. Pair with ADRs in `doc/adr/` for individual decisions.
+
+## Overview
+
+`<one paragraph: what the system does, key external dependencies, deployment shape>`
+
+## Layers & Boundaries
+
+`<the layered/hexagonal/clean structure: what lives in each layer, what crosses boundaries, what doesn't>`
+
+## Patterns
+
+* **Data access:** `<e.g., Repository pattern; raw SQL only inside `internal/db/`>`
+* **HTTP handlers:** `<e.g., all go through middleware in `src/middleware/`>`
+* **Async/messaging:** `<e.g., Kafka topics owned by their producer service>`
+* **Error handling:** `<e.g., domain errors in `errors/`; HTTP mapping at handler edge>`
+* **Validation:** `<e.g., Pydantic at boundary, never inside core>`
+
+## Naming Conventions
+
+`<module/file/class naming rules that aren't obvious from language defaults>`
+
+## Observability
+
+* Logs: `<format, level conventions, where they ship>`
+* Metrics: `<library, dashboards>`
+* Traces: `<provider, sampling strategy>`
+
+## Deployment Topology
+
+`<how services run in prod: containers, orchestration, scaling rules>`
+
+## Active ADRs
+
+Currently-binding decisions. Link each to `doc/adr/`.
+
+* ADR-0001 — `<title>`
+* ADR-0002 — `<title>`

package/templates/skill.md

@@ -0,0 +1,27 @@
+---
+description: <what the skill does + when to invoke — primary triggering signal>
+
+# Optional — declare only what you need.
+# name: <skill-name>                # lowercase + numbers + hyphens, ≤64 chars; defaults to directory name
+# when_to_use: <trigger phrases or example requests; appended to description>
+# argument-hint: <[issue-number] or [filename] [format]>
+# arguments: <space-separated names mapped to positions>
+# allowed-tools: Read Grep          # pre-approves tools while skill is active
+# disable-model-invocation: true    # only the user can invoke (no auto-load)
+# user-invocable: false             # only Claude can invoke (background knowledge)
+# context: fork                     # run in a forked subagent
+# agent: Explore                    # Explore | Plan | general-purpose | <custom>
+# paths: <glob,glob>                # auto-load only when working in matching files
+# model: <sonnet | opus | haiku | inherit>
+# effort: <low | medium | high | xhigh | max>
+# hooks: <see code.claude.com/docs/en/hooks>
+# shell: <bash | powershell>
+---
+
+<Imperative instructions: what to do, not why. State as standing rules — once
+loaded, the body stays in context for the rest of the session.>
+
+## Additional resources
+
+- For detailed reference: see [reference.md](reference.md)
+- For examples: see [examples.md](examples.md)

package/templates/subagent.md

@@ -0,0 +1,27 @@
+---
+# Required
+name: <unique-name>                  # lowercase + hyphens
+description: <when Claude should delegate to this subagent>
+
+# Optional — declare only what you need.
+# tools: Read, Glob, Grep            # comma-separated; omit to inherit all parent tools
+# disallowedTools: Write, Edit       # subtract from inherited or specified list
+# model: sonnet                      # sonnet | opus | haiku | <full-id> | inherit (default)
+# permissionMode: default            # default | acceptEdits | auto | dontAsk | bypassPermissions | plan
+# skills: skill-a, skill-b           # full skill content injected at startup
+# maxTurns: 10
+# memory: project                    # user | project | local — enables cross-session learnings
+# isolation: worktree                # run in a temporary git worktree
+# background: false
+# effort: medium                     # low | medium | high | xhigh | max
+# color: blue                        # red | blue | green | yellow | purple | orange | pink | cyan
+# mcpServers: <see code.claude.com/docs/en/mcp>
+# hooks: <see code.claude.com/docs/en/hooks>
+# initialPrompt: <auto-submitted as first user turn when run as main agent>
+---
+
+<System prompt: the subagent's role, scope, and stop criteria.
+
+State the role in one sentence. Define what it should do when invoked, what
+output format to return, and what NOT to do. The subagent does not read
+AGENTS.md — restate any convention it must follow.>