docs: update documentation for asset system

.changeset/add-asset-system.md

@@ -0,0 +1,13 @@
+---
+"dev-workflows": minor
+---
+
+Add asset system for commands, templates, hooks, and presets
+
+- **Commands**: `devw add command/spec` downloads slash commands that deploy to `.claude/commands/`
+- **Templates**: `devw add template/feature-spec` installs spec templates to `docs/specs/`
+- **Hooks**: `devw add hook/auto-format` merges editor hooks into `.claude/settings.local.json`
+- **Presets**: `devw add preset/spec-driven` installs a full workflow bundle (rules + commands + templates + hooks)
+- **Init with preset**: `devw init --preset spec-driven` scaffolds a project with a complete workflow
+- **Asset-aware commands**: `list`, `remove`, `doctor`, `watch`, and `compile` all support the new asset types
+- **Content**: 4 slash commands (spec, plan, build, learn), 1 template (feature-spec), 1 hook (auto-format), 1 preset (spec-driven), 1 rule (workflow/spec-driven)

README.md

@@ -6,29 +6,41 @@
 
 Define rules once. Compile them everywhere.
 
-A local-first CLI to define AI coding rules and compile them for every editor and agent.
+A local-first CLI to define AI coding rules, slash commands, templates, and hooks — compiled for every editor and agent.
 
 ---
 
 ## Quick Start
 
 ```bash
 npx dev-workflows init
-devw add react-conventions
+devw add typescript/strict
 devw compile
 ```
 
+Or bootstrap a full spec-driven workflow:
+
+```bash
+devw init --preset spec-driven -y
+```
+
 ---
 
 ## What it does
 
 ```
 .dwf/rules/*.yml        →  devw compile  →  CLAUDE.md
-                                             .cursor/rules
+                                             .cursor/rules/devworkflows.mdc
                                              GEMINI.md
+                                             .windsurf/rules/devworkflows.md
+                                             .github/copilot-instructions.md
+
+.dwf/assets/commands/*   →  devw compile  →  .claude/commands/*.md
+.dwf/assets/templates/*  →  devw compile  →  docs/specs/*.md
+.dwf/assets/hooks/*      →  devw compile  →  .claude/settings.local.json
 ```
 
-You define rules in YAML. The compiler generates each editor's native format. Change a rule, recompile — every editor stays in sync.
+You define rules in YAML and assets in Markdown/JSON. The compiler generates each editor's native format. Change a rule, recompile — every editor stays in sync.
 
 ---
 
@@ -37,29 +49,64 @@ You define rules in YAML. The compiler generates each editor's native format. Ch
 | Command | Description |
 |---------|-------------|
 | `devw init` | Initialize a `.dwf/` ruleset in your project |
-| `devw add <block>` | Install a prebuilt rule block |
-| `devw remove <block>` | Remove a rule block |
-| `devw compile` | Generate editor-specific rule files |
+| `devw init --preset <name>` | Initialize with a preset (e.g., `spec-driven`) |
+| `devw add <category>/<name>` | Install a rule from the registry |
+| `devw add command/<name>` | Install a slash command |
+| `devw add template/<name>` | Install a spec template |
+| `devw add hook/<name>` | Install an editor hook |
+| `devw add preset/<name>` | Install a preset (bundle of rules + assets) |
+| `devw remove <category>/<name>` | Remove a rule or asset |
+| `devw compile` | Generate editor configs and deploy assets |
 | `devw watch` | Watch `.dwf/` and recompile on changes |
-| `devw doctor` | Validate config and detect rule drift |
+| `devw doctor` | Validate config and detect drift |
 | `devw list rules` | List all active rules |
-| `devw list blocks` | List installed blocks |
+| `devw list assets` | List installed assets |
 | `devw list tools` | List configured editors |
 
 ---
 
-## Rule Blocks
+## Rules Registry
+
+Install rules from the registry with `devw add <category>/<rule>`.
+
+| Rule | Description |
+|------|-------------|
+| `typescript/strict` | Strict TypeScript patterns |
+| `javascript/react` | React component and hook conventions |
+| `javascript/nextjs` | Next.js App Router best practices |
+| `css/tailwind` | Utility-first styling conventions |
+| `testing/vitest` | Test naming and structure rules |
+| `security/supabase-rls` | Database security and RLS rules |
+| `security/auth-patterns` | Authentication best practices |
+| `frontend/design-guidelines` | UI/UX design conventions |
+| `frontend/accessibility` | Accessibility (a11y) rules |
+| `frontend/performance` | Frontend performance patterns |
+| `workflow/git-conventions` | Git commit and branch conventions |
+| `workflow/debugging` | Systematic debugging methodology |
+| `workflow/spec-driven` | Spec-driven development workflow |
+
+---
+
+## Assets
+
+Beyond rules, dev-workflows manages **assets** — slash commands, templates, and hooks that power AI workflows.
+
+| Asset | Type | Description |
+|-------|------|-------------|
+| `command/spec` | Command | Generate a feature spec through guided questions |
+| `command/plan` | Command | Create an implementation plan from a spec |
+| `command/build` | Command | Execute a plan step by step with verification |
+| `command/learn` | Command | Capture a lesson learned as a project rule |
+| `template/feature-spec` | Template | Markdown template for feature specifications |
+| `hook/auto-format` | Hook | Auto-format files after AI edits |
+
+### Presets
 
-Prebuilt rule blocks you can stack. Install with `devw add <block>`.
+Presets bundle rules and assets into a single install.
 
-| Block | Purpose |
-|-------|---------|
-| `typescript-strict` | Enforces strict TypeScript patterns |
-| `react-conventions` | Common React component and hook rules |
-| `nextjs-approuter` | Next.js App Router best practices |
-| `tailwind` | Utility-first styling conventions |
-| `supabase-rls` | Database security and RLS rules |
-| `testing-basics` | Test naming and structure rules |
+| Preset | Includes |
+|--------|----------|
+| `preset/spec-driven` | `workflow/spec-driven` rule + all 4 commands + feature-spec template + auto-format hook |
 
 ---
 
@@ -72,7 +119,7 @@ Bridges generate editor-compatible rule files. One adapter per tool.
 | Claude Code | `CLAUDE.md` |
 | Cursor | `.cursor/rules/devworkflows.mdc` |
 | Gemini CLI | `GEMINI.md` |
-| Windsurf | `.windsurfrules` |
+| Windsurf | `.windsurf/rules/devworkflows.md` |
 | VS Code Copilot | `.github/copilot-instructions.md` |
 
 ---
@@ -99,4 +146,4 @@ Issues and PRs welcome. If you find a bug or have an idea, [open an issue](https
 
 ## License
 
-MIT
+MIT

content/commands/build.md

@@ -0,0 +1,31 @@
+---
+name: build
+description: "Execute a plan step by step with verification"
+version: "0.1.0"
+tool: claude
+---
+You are a senior software engineer. Your job is to execute an implementation plan step by step.
+
+Follow this process:
+
+1. **Read the plan** provided by the user (a path to a plan file).
+
+2. **For each step in the plan:**
+   a. Announce which step you are starting
+   b. Make the code changes described
+   c. Run verification: tests, lint, and type checks
+   d. If verification passes, create a commit with the message from the plan
+   e. If verification fails, fix the issue before moving on
+
+3. **Rules:**
+   - Never skip a step
+   - Never combine steps into one commit
+   - Always run tests after each step
+   - If a step is unclear, ask for clarification before proceeding
+   - If a step fails after 3 attempts, stop and report the issue
+
+4. **After completing all steps:**
+   - Run the full test suite
+   - Report a summary: steps completed, tests passing, any issues
+
+Be methodical. Quality matters more than speed.

content/commands/learn.md

@@ -0,0 +1,32 @@
+---
+name: learn
+description: "Capture a lesson learned and add it as a project rule"
+version: "0.1.0"
+tool: claude
+---
+You are a knowledge capture assistant. Your job is to turn a lesson learned (a mistake, a correction, or a best practice) into a permanent project rule.
+
+Follow this process:
+
+1. **Ask the user** what they learned. This could be:
+   - A bug they found and how to avoid it
+   - A pattern that works well in this codebase
+   - A convention the AI should always follow
+   - A mistake the AI made that should not be repeated
+
+2. **Formulate a clear, actionable rule** from the lesson. The rule should:
+   - Be specific to this project
+   - Be written as an imperative instruction
+   - Include context about why it matters
+   - Be concise (1-3 sentences)
+
+3. **Append the rule** to the project's `CLAUDE.md` file (or equivalent) under a `## Lessons Learned` section. If the section does not exist, create it.
+
+Format:
+```
+## Lessons Learned
+
+- <Rule description>. Context: <why this matters>.
+```
+
+Confirm with the user before writing.

content/commands/plan.md

@@ -0,0 +1,45 @@
+---
+name: plan
+description: "Generate an implementation plan from a spec"
+version: "0.1.0"
+tool: claude
+---
+You are a senior software architect. Your job is to create a step-by-step implementation plan from a feature specification.
+
+Follow this process:
+
+1. **Read the spec** provided by the user (a path to a spec file in `docs/specs/`).
+
+2. **Analyze the codebase** to understand:
+   - Which files need to be created or modified
+   - Existing patterns to follow
+   - Dependencies and potential conflicts
+   - Test infrastructure
+
+3. **Generate the plan** with incremental, commit-ready chunks. Each step should:
+   - Be independently testable
+   - Build on the previous step
+   - Include specific file paths and function names
+   - Note what tests to write or update
+
+Use this format:
+
+```markdown
+# Plan: <feature-name>
+
+**Spec:** <path-to-spec>
+**Estimated steps:** N
+
+## Step 1: <title>
+**Files:** `path/to/file.ts`
+**Changes:**
+- Description of change 1
+- Description of change 2
+**Tests:** Description of tests to add
+**Commit message:** `type: description`
+
+## Step 2: <title>
+...
+```
+
+Each step should be small enough to review in one sitting. Prefer many small steps over few large ones.

content/commands/spec.md

@@ -0,0 +1,47 @@
+---
+name: spec
+description: "Generate a feature specification through guided questions"
+version: "0.1.0"
+tool: claude
+---
+You are a senior software architect. Your job is to create a clear, complete specification for a new feature.
+
+Follow this process:
+
+1. **Ask 3-5 clarifying questions** about the feature. Focus on:
+   - What problem does this solve?
+   - Who is the target user?
+   - What are the key constraints (performance, compatibility, etc.)?
+   - What does success look like?
+
+2. **Research the codebase** before writing. Look at:
+   - Existing patterns and conventions
+   - Related features that already exist
+   - Technology stack and dependencies
+
+3. **Generate the spec** in `docs/specs/<feature-name>.md` using this structure:
+
+```markdown
+# Feature: <name>
+
+## Summary
+One paragraph describing the feature and its purpose.
+
+## Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+## Technical Constraints
+- Constraint 1
+- Constraint 2
+
+## Edge Cases
+- Edge case 1
+- Edge case 2
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+```
+
+Wait for the user to answer your questions before generating the spec. Do not make assumptions.

content/hooks/auto-format.json

@@ -0,0 +1,16 @@
+{
+  "name": "auto-format",
+  "description": "Auto-format files after AI edits",
+  "version": "0.1.0",
+  "tool": "claude",
+  "settings": {
+    "hooks": {
+      "PostToolUse": [
+        {
+          "matcher": "Write|Edit",
+          "command": "pnpm format || true"
+        }
+      ]
+    }
+  }
+}

content/presets/spec-driven.yml

@@ -0,0 +1,15 @@
+name: spec-driven
+description: "Complete spec-driven AI development workflow"
+version: "0.1.0"
+includes:
+  rules:
+    - workflow/spec-driven
+  commands:
+    - spec
+    - plan
+    - build
+    - learn
+  templates:
+    - feature-spec
+  hooks:
+    - auto-format

content/rules/README.md

@@ -18,6 +18,7 @@ Rules for AI coding agents, distributed via `devw add`.
 | `workflow/git-conventions` | Workflow | Git workflow and commit conventions | `devw add workflow/git-conventions` |
 | `workflow/debugging` | Workflow | Systematic debugging methodology | `devw add workflow/debugging` |
 | `security/auth-patterns` | Security | Authentication and authorization best practices | `devw add security/auth-patterns` |
+| `workflow/spec-driven` | Workflow | Spec-driven development workflow | `devw add workflow/spec-driven` |
 
 ## Usage
 

content/rules/workflow/spec-driven.md

@@ -0,0 +1,26 @@
+---
+name: spec-driven
+description: "Spec-driven development workflow: spec, plan, build, ship"
+version: "0.1.0"
+scope: workflow
+tags: [workflow, spec-driven, methodology]
+---
+
+## Feature Development
+
+- Every new feature MUST start with a spec. Use `/spec <feature-name>` to generate one through guided questions. Never jump straight to code.
+- After the spec is approved, generate an implementation plan with `/plan docs/specs/<feature-name>.md`. The plan breaks work into commit-ready steps.
+- Execute the plan step by step with `/build <plan-path>`. Each step is verified with tests and committed independently.
+- When you learn something new (a mistake, a pattern, a convention), capture it with `/learn` so the knowledge persists.
+
+## Quality Gates
+
+- Never skip the spec phase for features that touch more than 3 files. Small fixes and typos can go directly to implementation.
+- Every plan step must include what tests to write or update. No step is complete without passing verification.
+- If a step fails verification after 3 attempts, stop and ask for human guidance instead of forcing a solution.
+
+## Specs
+
+- Specs live in `docs/specs/` and follow the feature-spec template. Keep them concise but complete.
+- A good spec answers: what problem, for whom, what constraints, what success looks like, and what is explicitly out of scope.
+- Update the spec if requirements change during implementation. The spec is the source of truth.