@brunosps00/dev-workflow 1.3.0 → 1.5.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "brunosps00-dev-workflow",
+  "owner": {
+    "name": "Bruno Santos"
+  },
+  "plugins": [
+    {
+      "name": "dev-workflow",
+      "source": "./",
+      "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "dev-workflow",
+  "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.",
+  "version": "1.5.0",
+  "author": {
+    "name": "Bruno Santos"
+  },
+  "homepage": "https://github.com/brunosantos/dev-workflow",
+  "license": "MIT",
+  "keywords": [
+    "ai",
+    "workflow",
+    "skills",
+    "claude",
+    "minimalism",
+    "verification",
+    "security"
+  ],
+  "skills": [
+    "./scaffold/skills/api-testing-recipes",
+    "./scaffold/skills/docker-compose-recipes",
+    "./scaffold/skills/dw-minimalism",
+    "./scaffold/skills/dw-search-first",
+    "./scaffold/skills/dw-simplification",
+    "./scaffold/skills/dw-verify",
+    "./scaffold/skills/humanizer",
+    "./scaffold/skills/remotion-best-practices",
+    "./scaffold/skills/security-review",
+    "./scaffold/skills/vercel-react-best-practices"
+  ]
+}

package/README.md

@@ -12,10 +12,11 @@ This will:
 1. Ask you to select a language (English or Portuguese)
 2. Create `.dw/commands/` with workflow commands
 3. Create `.dw/templates/` with document templates (PRD, TechSpec, Tasks, ADR, etc.)
-4. Create `.dw/rules/` (populated by `/dw-analyze-project`)
+4. Create `.dw/rules/` (populated by `/dw-analyze-project`) + a curated `.dw/rules-library/` declarative baseline per stack (loaded lazily via `.dw/config/stack-mappings.json`)
 5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `dw-ui-discipline`, `dw-testing-discipline`, `security-review`, etc.) to `.agents/skills/`
 6. Generate skill wrappers and project agents for Claude Code, Codex, Copilot, and OpenCode
 7. Configure MCP servers (Context7 + Playwright)
+8. Install enforcement hooks (git guardrails + a `SessionEnd` token-cost tracker → `.dw/metrics/costs.jsonl`) + a statusline (branch · active spec · minimalism mode · today's estimated spend) into `.claude/settings.json` (merge-aware — your own hooks/statusline are never overwritten)
 
 > **Compozy-inspired disciplines.** Since 0.5.0, dev-workflow bundles three primitives — `dw-verify`, `dw-memory`, `dw-review-rigor` — adapted from the [Compozy](https://github.com/compozy/compozy) project and invoked internally by existing commands. See [docs/compozy-integration.md](docs/compozy-integration.md) for what was ported and what was not.
 
@@ -24,9 +25,24 @@ Optional dependencies (Playwright browsers, react-doctor, Trivy, Semgrep, gitlea
 npx @brunosps00/dev-workflow install-deps
 ```
 
+### Install individual skills (à-la-carte)
+
+Beyond the full pipeline, the standalone disciplines are also published as a Claude Code plugin, so you can adopt one skill without scaffolding the whole workflow:
+
+```bash
+# Claude Code: add the marketplace, then install the plugin
+/plugin marketplace add brunosps00/dev-workflow
+/plugin install dev-workflow@brunosps00-dev-workflow
+
+# or via the skills ecosystem
+npx skills add brunosps00/dev-workflow
+```
+
+Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-first`, `dw-simplification`, `dw-verify`, `humanizer`, `security-review`, `vercel-react-best-practices`, `remotion-best-practices`, `api-testing-recipes`, `docker-compose-recipes`. The plugin manifest is generated from the skill registry (`npm run build:plugin`); pipeline-bound skills (`dw-execute-phase`, `dw-memory`, `dw-codebase-intel`, `dw-cli-run`) are intentionally not exported.
+
 ## Commands
 
-dev-workflow v1.3.0 ships **36 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v1.5.0 ships **37 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (3)
 
@@ -53,7 +69,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-commit`** | Atomic Conventional Commits for pending changes. Applies `dw-git-discipline` (one intent per commit, lint+tests+build green before). |
 | **`/dw-generate-pr [target]`** | Push the branch, draft a PR body with summary + test plan, open the browser. Hard gates: dw-verify PASS + secure-audit. |
 
-### Tier 3 — Specialty (11)
+### Tier 3 — Specialty (12)
 
 | Command | What |
 |---------|------|
@@ -64,6 +80,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-context-budget`** | Audits context overhead from commands, skills, agents, instruction files, and MCPs. |
 | **`/dw-harness-audit`** | Deterministic health scorecard for the dev-workflow install, agents, wrappers, MCPs, and gates. |
 | **`/dw-skill-health`** | Audits installed skills and agents for bloat, duplication, and missing references. |
+| **`/dw-learn`** | Synthesizes durable decisions (confidence-tagged), bugfixes, deviations, and git history into atomic confidence-weighted **instincts** you approve at `.dw/memory/instincts/`; can propose constitution principles. On-demand and human-in-the-loop — **no always-on observer**. |
 | **`/dw-new-project`** | Bootstrap a new project from empty directory. Stack interview, wraps official `create-*` tools, composes docker-compose for dev, seeds `.env`, scripts, CI, `.dw/rules/`. |
 | **`/dw-dockerize`** | Reads existing project, detects stack + runtime deps, proposes Dockerfile + docker-compose for dev/prod with explicit trade-offs (Conservative/Balanced/Bold). |
 | **`/dw-install-azure-skills`** | **Opt-in.** Clones curated Azure skills from [`MicrosoftDocs/Agent-Skills`](https://github.com/MicrosoftDocs/Agent-Skills) (CC-BY-4.0) into `.agents/skills/azure/` and registers the [Microsoft Learn MCP Server](https://learn.microsoft.com/en-us/training/support/mcp-get-started) (HTTP, no-auth). Interactive category selection (Compute / Data & Storage / AI & ML / Networking / Identity & Security / DevOps / Observability / Integration / Architecture / All). Re-run to refresh from upstream. Also available as CLI: `npx @brunosps00/dev-workflow install-azure-skills`. |
@@ -249,7 +266,7 @@ npx @brunosps00/dev-workflow subtask list
 
 ## Bundled Skills
 
-Skills installed to `.agents/skills/` for use by all commands. The bundle is governed by `scaffold/skill-registry.json`, which records each skill's kind, tier, owner, trigger, expected output, load policy, and context limit.
+Skills installed to `.agents/skills/` for use by all commands. The bundle is governed by `scaffold/skill-registry.json`, which records each skill's kind, tier, owner, trigger, expected output, load policy, context limit, invocation control (`model` vs `explicit`), and à-la-carte `exportable` flag.
 
 Skill kinds:
 
@@ -274,6 +291,7 @@ These are not slash commands — they are primitives other commands call to enfo
 | **dw-execute-phase** | Goal-backward 6-dimension plan verification (`plan-checker`) and wave-based parallel task execution (`executor`) with atomic commit, deviation handling, and checkpoint recovery | `/dw-run`, `/dw-goal`, `/dw-autopilot` | [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (MIT) |
 | **dw-source-grounding** | Detect → Fetch → Implement → Cite protocol with `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]` citations. Strict source-priority hierarchy (Tier 1 official docs > Tier 2 maintainer blogs > Tier 3 Stack Overflow as discovery only). | `/dw-plan techspec`, `/dw-secure-audit --plan`, `/dw-opportunities --research`, `/dw-brainstorm --research` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
 | **dw-simplification** | Chesterton's Fence (understand WHY before changing), behavior-preserving refactor protocol (test gate before/after), complexity metrics (cyclomatic, cognitive, depth, fan-out), Rule of 500 for large refactors | `/dw-review`, `/dw-refactor`, `/dw-brainstorm --mode=refactor-audit` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
+| **dw-minimalism** | Pre-generation YAGNI decision ladder (need it? reuse? stdlib? native? installed dep? one line?) with `lite`/`full`/`ultra` intensity. The missing rung between `dw-search-first` (dependencies) and `dw-simplification` (post-hoc cleanup). | `/dw-run`, `/dw-plan`, `/dw-review` | [`DietrichGebert/ponytail`](https://github.com/DietrichGebert/ponytail) (MIT) |
 | **dw-debug-protocol** | Stop-the-line discipline plus six-step triage (Reproduce → Localize → Reduce → Fix Root Cause → Guard → Verify End-to-End). Error categorization matrix; instrument-first non-reproducible-bug strategy. | `/dw-bugfix`, `/dw-qa --fix` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
 | **dw-git-discipline** | Trunk-based pattern (1-3 day branches, daily rebase, feature flags), atomic commit discipline (one intent per commit; refactor separate from feature), Conventional Commits, branch hygiene | `dw-commit`, `dw-generate-pr` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
 
@@ -347,6 +365,8 @@ Spec-Driven Development patterns — declarative constitution (`.dw/constitution
 
 UI discipline (`dw-ui-discipline`) and testing doctrine (`dw-testing-discipline`) are original works in this repository. Earlier dev-workflow versions (≤0.13.x) drew on `pedronauck/skills` `ui-craft` and `testing-boss` as inspiration, but in v0.14.0 those skills were rewritten clean-room after a license audit confirmed that the upstream repo has no explicit LICENSE file at root — the README's MIT claim is unverified. The underlying ideas (grounding before design; behavior over mocks; mutation over coverage) are widely-documented general software engineering principles available in many sources (Beck, Fowler, Meszaros, Feathers, Google SRE Book, WCAG specifications). Browser-DevTools patterns from [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) live inside `dw-testing-discipline/references/` (`security-boundary.md`, `three-workflow-patterns.md`).
 
+Minimalism discipline (`dw-minimalism`), per-skill invocation control (`disable-model-invocation` on hidden/internal command wrappers), the git-guardrails enforcement hook, and à-la-carte plugin distribution were adapted from [`DietrichGebert/ponytail`](https://github.com/DietrichGebert/ponytail) (MIT — the "lazy senior" decision ladder, intensity modes, and statusline) and [`mattpocock/skills`](https://github.com/mattpocock/skills) (MIT — user-vs-model invocation and `git-guardrails-claude-code`). See [docs/skills-ecosystem-comparison.md](docs/skills-ecosystem-comparison.md) for the full gap analysis and what was and was not adopted.
+
 Incident response (`dw-incident-response`) adapted from [`wilsto/claude-code-starter-kit/incident-response`](https://github.com/wilsto/claude-code-starter-kit) (MIT). The 5-phase workflow structure and runbook templates come from there. wilsto credits the upstream `wshobson/agents` plugin `incident-response` (v1.3.0); attribution chain preserved. Additional reading cited in the skill: Google SRE Book, Etsy Debriefing Facilitation Guide, PagerDuty Incident Response Documentation.
 
 LLM evaluation (`dw-llm-eval`) trajectory-match modes (strict / unordered / subset / superset) and tool-argument matching strategies adapted from [`langchain-ai/agentevals`](https://github.com/langchain-ai/agentevals) (MIT). The broader oracle-ladder framing, judge-calibration discipline, and reference-dataset principle are distilled from the open evaluations literature (OpenAI evals cookbook, Anthropic evals guidance, the academic eval-of-LLM body of work) and rewritten in our voice.

package/lib/build-plugin.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+const pkg = require('../package.json');
+const { readSkillRegistry } = require('./skill-registry');
+
+/**
+ * Generate the à-la-carte distribution manifests from the skill registry.
+ *
+ * Single source of truth: scaffold/skill-registry.json. Only skills marked
+ * `exportable: true` (standalone, no .dw/ pipeline dependency) are published.
+ * Re-run `npm run build:plugin` whenever the registry changes; CI validates
+ * that the committed manifests match.
+ *
+ * Writes:
+ *   .claude-plugin/plugin.json      — the dev-workflow skills plugin
+ *   .claude-plugin/marketplace.json — single-plugin marketplace listing
+ *
+ * This does NOT change the full-pipeline installer (`dev-workflow init`), which
+ * scaffolds all skills + commands into a project. The plugin is the parallel
+ * "install one skill" path.
+ */
+
+const REPO_ROOT = path.join(__dirname, '..');
+const PLUGIN_DIR = path.join(REPO_ROOT, '.claude-plugin');
+
+function buildManifests() {
+  const registry = readSkillRegistry();
+  const exportable = registry.skills
+    .filter((s) => s.exportable === true)
+    .map((s) => s.name)
+    .sort();
+
+  const author = typeof pkg.author === 'string' ? { name: pkg.author } : pkg.author || { name: 'Bruno Santos' };
+
+  const plugin = {
+    name: 'dev-workflow',
+    description:
+      'Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.',
+    version: pkg.version,
+    author,
+    homepage: (pkg.repository && pkg.repository.url) || undefined,
+    license: pkg.license,
+    keywords: ['ai', 'workflow', 'skills', 'claude', 'minimalism', 'verification', 'security'],
+    skills: exportable.map((name) => `./scaffold/skills/${name}`),
+  };
+
+  const marketplace = {
+    name: 'brunosps00-dev-workflow',
+    owner: author,
+    plugins: [
+      {
+        name: 'dev-workflow',
+        source: './',
+        description: plugin.description,
+      },
+    ],
+  };
+
+  return { plugin, marketplace, exportable };
+}
+
+function writeJsonStable(filePath, obj) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+}
+
+function run() {
+  const { plugin, marketplace, exportable } = buildManifests();
+  writeJsonStable(path.join(PLUGIN_DIR, 'plugin.json'), plugin);
+  writeJsonStable(path.join(PLUGIN_DIR, 'marketplace.json'), marketplace);
+  console.log(`Wrote .claude-plugin/plugin.json + marketplace.json (${exportable.length} exportable skills):`);
+  for (const name of exportable) console.log(`  - ${name}`);
+}
+
+module.exports = { buildManifests, run };
+
+if (require.main === module) {
+  run();
+}

package/lib/constants.js

@@ -5,10 +5,10 @@ const COMMANDS = {
     { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. First invocation plans and stops; second invocation resumes via dw-goal, then commit and PR.' },
     { name: 'dw-brainstorm', description: 'Refine a concrete idea against the product\'s existing features. Modes: ideation, --research, --onepager, --council. Use dw-opportunities before you have an idea and dw-refactor for code-health audits.' },
     { name: 'dw-bugfix', description: 'Trigger when user reports a bug, pastes an error, or describes broken behavior. Triages with three questions, then fixes or routes to PRD.' },
-    { name: 'dw-claude-run', description: 'Trigger when user asks to run/fire Claude (claude -p headless) in a dedicated worktree to implement a prepared prompt/spec. Claude adapter over the dw-cli-run protocol: durable audit log, resumable session via --session-id, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
-    { name: 'dw-codex-run', description: 'Trigger when user asks to run/fire Codex (codex exec) in a dedicated worktree to implement a prepared prompt/spec. Codex adapter over the dw-cli-run protocol: durable audit log, resumable per-task session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
+    { name: 'dw-claude-run', userInvoked: true, description: 'Trigger when user asks to run/fire Claude (claude -p headless) in a dedicated worktree to implement a prepared prompt/spec. Claude adapter over the dw-cli-run protocol: durable audit log, resumable session via --session-id, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
+    { name: 'dw-codex-run', userInvoked: true, description: 'Trigger when user asks to run/fire Codex (codex exec) in a dedicated worktree to implement a prepared prompt/spec. Codex adapter over the dw-cli-run protocol: durable audit log, resumable per-task session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
     { name: 'dw-commit', description: 'Trigger when implementation is complete and pending changes need to be committed. Atomic commits with Conventional Commits messages.' },
-    { name: 'dw-copilot-run', description: 'Trigger when user asks to run/fire GitHub Copilot CLI (copilot -p) in a dedicated worktree to implement a prepared prompt/spec. Copilot adapter over the dw-cli-run protocol: durable audit log, resumable session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
+    { name: 'dw-copilot-run', userInvoked: true, description: 'Trigger when user asks to run/fire GitHub Copilot CLI (copilot -p) in a dedicated worktree to implement a prepared prompt/spec. Copilot adapter over the dw-cli-run protocol: durable audit log, resumable session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
     { name: 'dw-dockerize', description: 'Reads a project, detects the stack and runtime deps, then proposes Dockerfile and docker-compose for dev and prod with explicit trade-offs.' },
     { name: 'dw-find-skills', description: 'Searches the npx skills ecosystem for a skill matching what you need, vets it, and installs it where you choose.' },
     { name: 'dw-functional-doc', description: 'Maps screens and user flows into a functional doc, validated end-to-end with Playwright.' },
@@ -20,6 +20,7 @@ const COMMANDS = {
     { name: 'dw-install-aws-skills', description: 'Trigger when user asks to install AWS expertise, setup AWS MCP server, or add AWS agent skills. Opt-in: clones curated skills from aws/agent-toolkit-for-aws into .agents/skills/aws/ and registers the unified AWS MCP Server (stdio via mcp-proxy-for-aws). Requires uv, aws cli, and AWS credentials.' },
     { name: 'dw-install-azure-skills', description: 'Trigger when user asks to install Azure expertise, setup Microsoft docs MCP, or add Azure agent skills. Opt-in: clones curated skills from MicrosoftDocs/Agent-Skills into .agents/skills/azure/ and registers the Microsoft Learn MCP server.' },
     { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
+    { name: 'dw-learn', description: 'Synthesizes durable decisions, bugfixes, deviations, and git history into atomic confidence-weighted instincts you approve; can propose constitution principles. On-demand and human-in-the-loop — no always-on observer.' },
     { name: 'dw-new-project', description: 'Interviews you about stack and infra, then scaffolds a working monorepo with docker-compose for dev, .env, scripts, CI, and seeded rules.' },
     { name: 'dw-opportunities', description: 'Scans the installed project for product, UX, automation, refactor, and security opportunities, then routes each idea to the right next dw-* command.' },
     { name: 'dw-pause', description: 'Trigger when user says "pause work", "end session", or "save where we are". Consolidates open loops, decisions, blockers, and todos into .dw/STATE.md so the next session can resume.' },
@@ -32,9 +33,9 @@ const COMMANDS = {
     { name: 'dw-run', description: 'Trigger when user wants to execute tasks. Default runs all pending in dependency order; \'run <task-id>\' runs one; \'run --resume\' continues an interrupted plan.' },
     { name: 'dw-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH block. Auto-invoked by /dw-review and /dw-generate-pr, explicit phase in /dw-autopilot, and runnable standalone.' },
     { name: 'dw-skill-health', description: 'Audits installed skills and agents for bloat, duplication, missing references, and stale or unused modules.' },
-    { name: 'dw-subtask-start', description: 'Creates a minimal input packet for a subagent without injecting the parent transcript.' },
-    { name: 'dw-subtask-complete', description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
-    { name: 'dw-subtask-resume', description: 'Consumes pending subagent handoffs, summarizes them for the parent, and archives the local packets.' },
+    { name: 'dw-subtask-start', userInvoked: true, description: 'Creates a minimal input packet for a subagent without injecting the parent transcript.' },
+    { name: 'dw-subtask-complete', userInvoked: true, description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
+    { name: 'dw-subtask-resume', userInvoked: true, description: 'Consumes pending subagent handoffs, summarizes them for the parent, and archives the local packets.' },
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
   ],
   'pt-br': [
@@ -43,10 +44,10 @@ const COMMANDS = {
     { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Primeira invocacao planeja e para; segunda retoma via dw-goal, depois commit e PR.' },
     { name: 'dw-brainstorm', description: 'Refina uma ideia concreta contra features existentes do produto. Modos: ideacao, --research, --onepager, --council. Use dw-opportunities antes de ter uma ideia e dw-refactor para auditoria de code health.' },
     { name: 'dw-bugfix', description: 'Trigger quando usuario reporta bug, cola erro ou descreve comportamento quebrado. Tria com tres perguntas, depois corrige ou roteia pra PRD.' },
-    { name: 'dw-claude-run', description: 'Trigger quando usuario pede pra rodar/disparar o Claude (claude -p headless) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Claude sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel via --session-id, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
-    { name: 'dw-codex-run', description: 'Trigger quando usuario pede pra rodar/disparar o Codex (codex exec) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Codex sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel por tarefa, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
+    { name: 'dw-claude-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Claude (claude -p headless) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Claude sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel via --session-id, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
+    { name: 'dw-codex-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Codex (codex exec) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Codex sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel por tarefa, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
     { name: 'dw-commit', description: 'Trigger quando implementacao esta completa e ha mudancas pendentes pra commit. Commits atomicos com mensagens Conventional Commits.' },
-    { name: 'dw-copilot-run', description: 'Trigger quando usuario pede pra rodar/disparar o GitHub Copilot CLI (copilot -p) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Copilot sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
+    { name: 'dw-copilot-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o GitHub Copilot CLI (copilot -p) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Copilot sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
     { name: 'dw-dockerize', description: 'Le um projeto, detecta stack e deps de runtime, e propoe Dockerfile e docker-compose para dev e prod com trade-offs explicitos.' },
     { name: 'dw-find-skills', description: 'Busca no ecossistema npx skills uma skill que resolva o que voce precisa, valida e instala onde voce escolher.' },
     { name: 'dw-functional-doc', description: 'Mapeia telas e fluxos em um dossie funcional, validado E2E com Playwright.' },
@@ -58,6 +59,7 @@ const COMMANDS = {
     { name: 'dw-install-aws-skills', description: 'Trigger quando usuario pede pra instalar expertise AWS, configurar MCP da AWS, ou adicionar agent skills AWS. Opt-in: clona skills curadas de aws/agent-toolkit-for-aws para .agents/skills/aws/ e registra o AWS MCP Server unificado (stdio via mcp-proxy-for-aws). Requer uv, aws cli e credenciais AWS.' },
     { name: 'dw-install-azure-skills', description: 'Trigger quando usuario pede pra instalar expertise Azure, configurar MCP do Microsoft docs, ou adicionar agent skills Azure. Opt-in: clona skills curadas de MicrosoftDocs/Agent-Skills para .agents/skills/azure/ e registra o Microsoft Learn MCP server.' },
     { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
+    { name: 'dw-learn', description: 'Sintetiza decisoes duraveis, bugfixes, deviations e historico git em instincts atomicos ponderados por confianca que voce aprova; pode propor principios de constitution. On-demand e human-in-the-loop — sem observador sempre-ligado.' },
     { name: 'dw-new-project', description: 'Entrevista voce sobre stack e infra, depois faz scaffold de um monorepo com docker-compose para dev, .env, scripts, CI e rules seed.' },
     { name: 'dw-opportunities', description: 'Escaneia o projeto instalado por oportunidades de produto, UX, automacao, refactor e seguranca, e roteia cada ideia para o proximo comando dw-* correto.' },
     { name: 'dw-pause', description: 'Trigger quando usuario diz "pausa o trabalho", "encerra a sessao" ou "salva onde paramos". Consolida pontas soltas, decisoes, bloqueios e todos em .dw/STATE.md para a proxima sessao retomar.' },
@@ -70,9 +72,9 @@ const COMMANDS = {
     { name: 'dw-run', description: 'Trigger quando usuario quer executar tasks. Default roda todas pendentes em ordem de dependencia; \'run <task-id>\' roda uma; \'run --resume\' continua plan interrompido.' },
     { name: 'dw-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH bloqueiam. Auto-invocado por /dw-review e /dw-generate-pr, fase explicita no /dw-autopilot, e executavel standalone.' },
     { name: 'dw-skill-health', description: 'Audita skills e agentes instalados por bloat, duplicacao, referencias quebradas e modulos sem uso.' },
-    { name: 'dw-subtask-start', description: 'Cria um input packet minimo para subagente sem injetar transcript bruto do parent.' },
-    { name: 'dw-subtask-complete', description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },
-    { name: 'dw-subtask-resume', description: 'Consome handoffs pendentes de subagentes, resume para o parent e arquiva os pacotes locais.' },
+    { name: 'dw-subtask-start', userInvoked: true, description: 'Cria um input packet minimo para subagente sem injetar transcript bruto do parent.' },
+    { name: 'dw-subtask-complete', userInvoked: true, description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },
+    { name: 'dw-subtask-resume', userInvoked: true, description: 'Consome handoffs pendentes de subagentes, resume para o parent e arquiva os pacotes locais.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },
   ],
 };
@@ -80,9 +82,12 @@ const COMMANDS = {
 const PLATFORMS = {
   claude: {
     dir: '.claude/skills',
-    wrapperTemplate: (name, description) => `---
+    // opts.userInvoked → emit disable-model-invocation: true so Claude Code never
+    // auto-fires hidden/internal commands (e.g. the worktree runners); the user
+    // still invokes them explicitly with /<name>.
+    wrapperTemplate: (name, description, opts = {}) => `---
 name: ${name}
-description: "${description.replace(/"/g, '\\"')}"
+description: "${description.replace(/"/g, '\\"')}"${opts.userInvoked ? '\ndisable-model-invocation: true' : ''}
 ---
 
 Read and follow ALL instructions in \`.dw/commands/${name}.md\`.

package/lib/doctor.js

@@ -10,6 +10,7 @@ const {
 } = require('./agents');
 const { readInstallState, STATE_RELATIVE_PATH } = require('./install-state');
 const { validateSkillRegistry, readSkillRegistry, validateSkillStructuredReturn } = require('./skill-registry');
+const { GIT_GUARDRAILS_CMD, STATUSLINE_CMD, HOOKS_DIR_MARKER } = require('./hooks');
 const removedCommands = require('./removed-commands');
 
 function run() {
@@ -33,6 +34,7 @@ function run() {
   checkSubtaskLayout(projectRoot, issues);
   checkSkillRegistry(projectRoot, issues, warnings);
   checkMcp(projectRoot, issues);
+  checkHooks(projectRoot, issues, warnings);
   checkLegacyCommands(projectRoot, warnings);
 
   console.log('dev-workflow doctor\n');
@@ -203,6 +205,37 @@ function checkMcp(projectRoot, issues) {
   }
 }
 
+function checkHooks(projectRoot, issues, warnings) {
+  // Hook scripts (copied from scaffold/scripts/ into .dw/scripts/).
+  for (const script of ['git-guardrails.mjs', 'statusline.mjs']) {
+    const file = path.join(projectRoot, '.dw', 'scripts', 'hooks', script);
+    if (!fs.existsSync(file)) issues.push(`Missing hook script: ${path.relative(projectRoot, file)}`);
+  }
+
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  if (!fs.existsSync(settingsPath)) return; // checkMcp already reports this
+
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+  } catch {
+    return; // checkMcp already reports malformed settings
+  }
+
+  const preToolUse = (settings.hooks && settings.hooks.PreToolUse) || [];
+  const guardrailWired = preToolUse.some(
+    (g) => g && Array.isArray(g.hooks) && g.hooks.some((h) => h && h.command === GIT_GUARDRAILS_CMD),
+  );
+  if (!guardrailWired) issues.push('Missing git-guardrails PreToolUse hook in .claude/settings.json');
+
+  const statusLine = settings.statusLine;
+  if (!statusLine) {
+    issues.push('Missing statusLine in .claude/settings.json');
+  } else if (statusLine.command !== STATUSLINE_CMD && !String(statusLine.command || '').includes(HOOKS_DIR_MARKER)) {
+    warnings.push('Custom statusLine set; dev-workflow statusline is not active (add `node .dw/scripts/hooks/statusline.mjs`).');
+  }
+}
+
 function checkLegacyCommands(projectRoot, warnings) {
   for (const entry of removedCommands) {
     const file = path.join(projectRoot, '.dw', 'commands', `${entry.name}.md`);

package/lib/hooks.js

@@ -0,0 +1,179 @@
+const { readSettings, writeSettings } = require('./mcp');
+
+// dev-workflow-owned hook/statusline scripts live under this path. The substring
+// is the marker used to identify OUR entries in .claude/settings.json so we can
+// add/refresh them on update without ever touching the user's own hooks.
+const HOOKS_DIR_MARKER = '.dw/scripts/hooks/';
+const GIT_GUARDRAILS_CMD = 'node .dw/scripts/hooks/git-guardrails.mjs';
+const STATUSLINE_CMD = 'node .dw/scripts/hooks/statusline.mjs';
+const GIT_GUARDRAILS_SCRIPT = 'git-guardrails.mjs';
+const SESSION_COST_CMD = 'node .dw/scripts/hooks/session-cost.mjs';
+const SESSION_COST_SCRIPT = 'session-cost.mjs';
+
+function isOurs(command) {
+  return typeof command === 'string' && command.includes(HOOKS_DIR_MARKER);
+}
+
+/**
+ * Reconcile dev-workflow hooks + statusLine into .claude/settings.json.
+ *
+ * Marker-based and merge-aware (unlike installMCPs' add-if-missing):
+ *  - adds our entries when absent;
+ *  - refreshes our entries in place when the script path/shape changed (so an
+ *    update actually updates);
+ *  - never removes or rewrites hooks/statusLine the user added;
+ *  - leaves a user-defined statusLine untouched (reports it so the caller can
+ *    surface a post-update note).
+ *
+ * Returns { hooks, statusLine } where each is 'added' | 'updated' | 'unchanged'
+ * (statusLine may also be 'skipped-user').
+ */
+function installHooks(projectRoot) {
+  const settings = readSettings(projectRoot);
+  const before = JSON.stringify(settings);
+
+  const hooksResult = reconcilePreToolUseGitGuardrails(settings);
+  const sessionCostResult = reconcileSessionEndCost(settings);
+  const statusLineResult = reconcileStatusLine(settings);
+
+  if (JSON.stringify(settings) !== before) {
+    writeSettings(projectRoot, settings);
+  }
+
+  return { hooks: hooksResult, sessionCost: sessionCostResult, statusLine: statusLineResult };
+}
+
+/**
+ * Reconcile the SessionEnd cost-tracking hook (marker-based, merge-aware — same
+ * contract as the git guardrail). No matcher: fires on every session end.
+ * Returns 'added' | 'updated' | 'unchanged'.
+ */
+function reconcileSessionEndCost(settings) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+  if (!Array.isArray(settings.hooks.SessionEnd)) settings.hooks.SessionEnd = [];
+
+  const groups = settings.hooks.SessionEnd;
+
+  const existed = groups.some(
+    (g) => g && Array.isArray(g.hooks) && g.hooks.some((h) => h && typeof h.command === 'string' && h.command.includes(SESSION_COST_SCRIPT)),
+  );
+  const exactPresent = groups.some(
+    (g) => g && Array.isArray(g.hooks) && g.hooks.some((h) => h && h.command === SESSION_COST_CMD),
+  );
+
+  if (exactPresent) return 'unchanged';
+
+  // Drop any stale/relocated copies of OUR hook, preserving user hooks.
+  for (const group of groups) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    group.hooks = group.hooks.filter(
+      (h) => !(h && typeof h.command === 'string' && h.command.includes(SESSION_COST_SCRIPT)),
+    );
+  }
+  settings.hooks.SessionEnd = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
+
+  settings.hooks.SessionEnd.push({ hooks: [{ type: 'command', command: SESSION_COST_CMD }] });
+
+  return existed ? 'updated' : 'added';
+}
+
+function reconcilePreToolUseGitGuardrails(settings) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
+
+  const groups = settings.hooks.PreToolUse;
+
+  // Was our guardrail already wired (anywhere, any shape)?
+  const existed = groups.some(
+    (g) =>
+      g && Array.isArray(g.hooks) && g.hooks.some((h) => h && typeof h.command === 'string' && h.command.includes(GIT_GUARDRAILS_SCRIPT)),
+  );
+  // Already wired with the exact canonical command in a Bash group?
+  const exactPresent = groups.some(
+    (g) =>
+      g && g.matcher === 'Bash' && Array.isArray(g.hooks) && g.hooks.some((h) => h && h.command === GIT_GUARDRAILS_CMD),
+  );
+
+  if (exactPresent) return 'unchanged';
+
+  // Drop any stale/relocated copies of OUR guardrail, preserving user hooks.
+  for (const group of groups) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    group.hooks = group.hooks.filter(
+      (h) => !(h && typeof h.command === 'string' && h.command.includes(GIT_GUARDRAILS_SCRIPT)),
+    );
+  }
+  // Prune groups we just emptied (only those left with zero hooks).
+  settings.hooks.PreToolUse = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
+
+  // Re-add the canonical entry: into an existing Bash group if present, else new.
+  const bashGroup = settings.hooks.PreToolUse.find((g) => g && g.matcher === 'Bash' && Array.isArray(g.hooks));
+  if (bashGroup) {
+    bashGroup.hooks.push({ type: 'command', command: GIT_GUARDRAILS_CMD });
+  } else {
+    settings.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [{ type: 'command', command: GIT_GUARDRAILS_CMD }] });
+  }
+
+  return existed ? 'updated' : 'added';
+}
+
+function reconcileStatusLine(settings) {
+  const desired = { type: 'command', command: STATUSLINE_CMD };
+  const current = settings.statusLine;
+
+  if (!current) {
+    settings.statusLine = desired;
+    return 'added';
+  }
+  // Only manage a statusLine we own; never clobber a user's custom one.
+  if (current.command === STATUSLINE_CMD) return 'unchanged';
+  if (isOurs(current.command)) {
+    settings.statusLine = desired; // our script moved/renamed — refresh
+    return 'updated';
+  }
+  return 'skipped-user';
+}
+
+/**
+ * Remove ONLY dev-workflow-owned hook + statusLine entries (used by uninstall).
+ * Returns the number of entries removed.
+ */
+function removeHooks(projectRoot) {
+  const settings = readSettings(projectRoot);
+  let removed = 0;
+
+  // Remove OUR hook entries from every event (PreToolUse, SessionEnd, PostToolUse, …),
+  // identified by the .dw/scripts/hooks/ marker; never touch user-added hooks.
+  if (settings.hooks && typeof settings.hooks === 'object') {
+    for (const event of Object.keys(settings.hooks)) {
+      const groups = settings.hooks[event];
+      if (!Array.isArray(groups)) continue;
+      for (const group of groups) {
+        if (!group || !Array.isArray(group.hooks)) continue;
+        const kept = group.hooks.filter((h) => !(h && isOurs(h.command)));
+        removed += group.hooks.length - kept.length;
+        group.hooks = kept;
+      }
+      settings.hooks[event] = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
+      if (settings.hooks[event].length === 0) delete settings.hooks[event];
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  }
+
+  if (settings.statusLine && isOurs(settings.statusLine.command)) {
+    delete settings.statusLine;
+    removed++;
+  }
+
+  if (removed > 0) writeSettings(projectRoot, settings);
+  return removed;
+}
+
+module.exports = {
+  installHooks,
+  removeHooks,
+  HOOKS_DIR_MARKER,
+  GIT_GUARDRAILS_CMD,
+  STATUSLINE_CMD,
+  SESSION_COST_CMD,
+};

package/lib/init.js

@@ -4,6 +4,7 @@ const { ensureDir, copyDir, writeFile, upsertDelimitedBlock, log, listFilesRecur
 const { selectLanguage } = require('./prompts');
 const { generateWrappers } = require('./wrappers');
 const { installMCPs } = require('./mcp');
+const { installHooks } = require('./hooks');
 const { generateAgents } = require('./agents');
 const { migrate: migrateGsd } = require('./migrate-gsd');
 const { migrate: migrateSkills } = require('./migrate-skills');
@@ -169,6 +170,30 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     console.log();
   }
 
+  // 3.9. Copy curated rules library + stack mappings (declarative baseline per stack,
+  // loaded lazily by the detected stack). Managed: reconciled on update/repair.
+  const rulesLibSrc = path.join(SCAFFOLD_DIR, 'rules');
+  if (require('fs').existsSync(rulesLibSrc)) {
+    console.log('  Rules library:');
+    const rlResults = copyDir(rulesLibSrc, path.join(projectRoot, '.dw', 'rules-library'), managedForce);
+    totalCreated += rlResults.created;
+    totalSkipped += rlResults.skipped;
+    totalOverwritten += rlResults.overwritten;
+    touchedFiles.push(...listFilesRecursive(path.join(projectRoot, '.dw', 'rules-library')));
+    console.log(`    ${rlResults.created} created, ${rlResults.skipped} skipped, ${rlResults.overwritten} overwritten\n`);
+  }
+  const stackMapSrc = path.join(SCAFFOLD_DIR, 'config', 'stack-mappings.json');
+  if (require('fs').existsSync(stackMapSrc)) {
+    const cfgDir = path.join(projectRoot, '.dw', 'config');
+    ensureDir(cfgDir);
+    const stackMapDest = path.join(cfgDir, 'stack-mappings.json');
+    const smStatus = writeFile(stackMapDest, require('fs').readFileSync(stackMapSrc, 'utf-8'), managedForce);
+    if (smStatus === 'created') totalCreated++;
+    else if (smStatus === 'overwritten') totalOverwritten++;
+    else totalSkipped++;
+    touchedFiles.push(stackMapDest);
+  }
+
   // 4. Create .dw/rules/ with README
   if (!isUpdate) {
     console.log('  Rules:');
@@ -211,6 +236,16 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     console.log();
   }
 
+  // 5.15. Seed .dw/minimalism.json (init only; preserved on update). Holds the
+  // dw-minimalism intensity mode read by the skill and the statusline hook.
+  if (!isUpdate) {
+    const minimalismPath = path.join(projectRoot, '.dw', 'minimalism.json');
+    const minimalismStatus = writeFile(minimalismPath, JSON.stringify({ mode: 'full' }, null, 2) + '\n', false);
+    if (minimalismStatus === 'created') totalCreated++;
+    else totalSkipped++;
+    touchedFiles.push(minimalismPath);
+  }
+
   // 5.2. Create .dw/bugfixes/ with .gitkeep (init only; preserved on update)
   if (!isUpdate) {
     const bugfixesDir = path.join(projectRoot, '.dw', 'bugfixes');
@@ -222,6 +257,30 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     touchedFiles.push(gitkeepPath);
   }
 
+  // 5.25. Ensure .dw/metrics/ + .gitignore (runtime cost tracking; costs.jsonl is
+  // machine-local so it is gitignored). Created if missing on both init and update.
+  {
+    const metricsDir = path.join(projectRoot, '.dw', 'metrics');
+    ensureDir(metricsDir);
+    const metricsGitignore = path.join(metricsDir, '.gitignore');
+    const mStatus = writeFile(metricsGitignore, 'costs.jsonl\n', false);
+    if (mStatus === 'created') totalCreated++;
+    else totalSkipped++;
+    touchedFiles.push(metricsGitignore);
+  }
+
+  // 5.26. Ensure .dw/memory/instincts/ (durable learnings promoted by /dw-learn;
+  // format in the dw-memory skill's references/instincts.md). Init only; preserved on update.
+  if (!isUpdate) {
+    const instinctsDir = path.join(projectRoot, '.dw', 'memory', 'instincts');
+    ensureDir(instinctsDir);
+    const instinctsKeep = path.join(instinctsDir, '.gitkeep');
+    const ikStatus = writeFile(instinctsKeep, '', false);
+    if (ikStatus === 'created') totalCreated++;
+    else totalSkipped++;
+    touchedFiles.push(instinctsKeep);
+  }
+
   // 5.3. Create local ephemeral subtask handoff directories.
   ensureSubtaskLayout(projectRoot);
   touchedFiles.push(path.join(projectRoot, '.dw', 'subtasks', '.gitignore'));
@@ -302,6 +361,15 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
   const mcpResults = installMCPs(projectRoot);
   console.log(`    ${mcpResults.added} configured, ${mcpResults.skipped} already present\n`);
 
+  // 9.2. Reconcile dev-workflow hooks + statusline (marker-based, merge-aware:
+  // refreshes our entries, never touches user-defined hooks/statusLine).
+  console.log('  Hooks & statusline:');
+  const hookResults = installHooks(projectRoot);
+  console.log(`    git-guardrails: ${hookResults.hooks}, session-cost: ${hookResults.sessionCost}, statusline: ${hookResults.statusLine}\n`);
+  if (hookResults.statusLine === 'skipped-user') {
+    console.log('    Note: a custom statusLine is set; to show dev-workflow state add `node .dw/scripts/hooks/statusline.mjs`.\n');
+  }
+
   // 9.5. Persist install state for diagnostics and repair.
   const installState = writeInstallState(projectRoot, {
     lang: selectedLang,