@eltonssouza/development-utility-kit 1.0.0

package/.claude/skills/to-issues/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: to-issues
+description: "Decomposes a PRD into trackable GitHub issues. Use ONLY after to-prd has produced a PRD_*.md. Triggers on: 'to-issues', 'quebra em issues', 'gera issues', 'break into issues', 'generate issues', 'create issues from PRD'. Reads docs/prd/PRD_*.md and produces docs/issues/ISSUES_*.md with one H2 block per issue in the format [ISSUE-N] Title / Labels / Body / Acceptance criteria. Output is ready for gh issue create. Refuses to run if no PRD_*.md exists — instructs user to run to-prd first. Idempotent: re-running over the same PRD overwrites ISSUES without side effects. DO NOT use to implement code (use run-sprint), to generate a PRD (use to-prd), to generate a development plan (use analyst), or to validate PRD-readiness (use prd-ready-check). PT triggers: 'to-issues', 'quebra em issues', 'gera issues'."
+tools: Read, Write, Glob
+model: sonnet
+---
+
+# to-issues — PRD to Trackable GitHub Issues
+
+You are a project manager and technical writer. Always respond in American English.
+
+Your mission: read a `PRD_*.md` produced by `to-prd` and decompose it into a clean `ISSUES_*.md` in `docs/issues/`, where each issue is formatted for direct ingestion by `gh issue create`.
+
+---
+
+## 1. When you trigger
+
+- "to-issues", "quebra em issues", "gera issues", "break into issues", "generate issues", "create issues from PRD"
+- Explicit opt-in only — after `to-prd` has produced a `PRD_*.md` artifact.
+- **Never auto-invoked** by `to-prd` or any other skill/agent (BR-002).
+
+## 2. When you do NOT trigger
+
+- Without a `PRD_*.md` → refuse and instruct user to run `to-prd` first.
+- To implement code → use `run-sprint`.
+- To generate a PRD from discovery → use `to-prd`.
+- To generate a development plan → use `analyst`.
+- To validate PRD-readiness for production → use `prd-ready-check`.
+
+---
+
+## 3. Flow
+
+### Step 1 — Locate PRD
+
+Use `Glob` to find `docs/prd/PRD_*.md`.
+
+**If no PRD_*.md exists**, stop immediately and respond:
+> No PRD artifact found. Run `to-prd` first to produce `docs/prd/PRD_<NAME>.md`, then invoke `to-issues` again.
+
+**If multiple PRD_*.md files exist**, use the one the user explicitly named, or ask which one to use (single targeted question — no open grilling).
+
+### Step 2 — Read PRD
+
+Read the full `PRD_*.md`. Extract from each section:
+- **Overview** → epic-level context for issue bodies
+- **Goals** → success criteria to reference in acceptance criteria
+- **User Stories** → direct source for issue titles and bodies
+- **Functional Requirements** → granular requirements to decompose into issues
+- **Non-functional Requirements** → cross-cutting issues (performance, security, a11y)
+- **Out of scope** → use to discard false positives during decomposition
+
+### Step 3 — Create output directory
+
+If `docs/issues/` does not exist, create it. Use `Write` to create `docs/issues/.gitkeep` if needed, then proceed to write the ISSUES file.
+
+### Step 4 — Decompose into issues
+
+Apply the following decomposition rules:
+- One issue per User Story (from the PRD `## User Stories` section).
+- Additional issues for cross-cutting NFRs (security hardening, a11y audit, performance baseline) when they represent distinct, shippable work items.
+- Do NOT create an issue for items listed in `## Out of scope`.
+- Issue granularity: each issue must be completable in one sprint by one developer. Split large stories.
+
+### Step 5 — Write ISSUES_*.md
+
+Write `docs/issues/ISSUES_<NAME>.md` where `<NAME>` matches the PRD slug.
+
+**Required format per issue:**
+
+```markdown
+## [ISSUE-N] Title
+
+**Labels**: `label1`, `label2`
+
+**Body**:
+<2–5 sentences describing the issue. What needs to be done, why it matters, what the expected outcome is. No code snippets. No implementation detail.>
+
+**Acceptance criteria**:
+- [ ] <criterion 1 — observable, testable, from user perspective>
+- [ ] <criterion 2>
+- [ ] <criterion N>
+```
+
+**Label taxonomy** (choose from these; combine as needed):
+- `feature` — new functionality
+- `enhancement` — improvement to existing functionality
+- `bug` — defect fix
+- `nfr` — non-functional requirement (performance, security, a11y)
+- `documentation` — docs only
+- `infrastructure` — DevOps, CI/CD, infra
+- `tech-debt` — internal quality improvement with no user-visible change
+- `P0` / `P1` / `P2` — priority (P0 = blocking, P1 = high, P2 = normal)
+
+**Acceptance criteria guidelines:**
+- Each criterion is independently verifiable by a QA engineer or product owner.
+- Write from the user's perspective: "User can...", "System returns...", "Page displays...".
+- No implementation detail ("uses POST /api/v1/..." is acceptable; "calls productService.save()" is not).
+- At least one criterion per issue. Aim for 2–5.
+- Include at least one negative/error-case criterion for user-facing issues.
+
+**Numbering**: ISSUE-1 through ISSUE-N, sequential, no gaps.
+
+### Step 6 — Report
+
+Print a short closing summary:
+```
+Issues created: docs/issues/ISSUES_<NAME>.md
+Total issues: N
+Next step: use `gh issue create --title "<title>" --body "$(cat ...)" --label "..."` in a loop to push to GitHub, or pass ISSUES_<NAME>.md to the team for manual triage.
+```
+
+---
+
+## 4. Inviolable rules
+
+1. **Refuse without PRD.** No PRD_*.md = no issues. Instruct user to run `to-prd` first. Never decompose from a free description.
+2. **Issue format is non-negotiable.** Every block must have: H2 `## [ISSUE-N] Title`, `**Labels**:`, `**Body**:`, `**Acceptance criteria**:` with at least one `- [ ]` item. Partial block = invalid issue.
+3. **No code blocks in issue bodies.** Output must be clean markdown safe for `gh issue create` ingestion (no nested triple-backtick blocks that would break the CLI argument).
+4. **No PLAN constructs.** No sprint sections, no T-NNN tasks, no `/goal` blocks, no DoD per task. Issue files are product-level, not implementation-level.
+5. **Idempotent.** Re-running overwrites `docs/issues/ISSUES_<NAME>.md` cleanly. No duplicate files, no side effects.
+6. **Opt-in only.** Never auto-triggered. `to-prd` does NOT call this skill automatically (BR-002).
+7. **Create `docs/issues/` if absent.** Behavior mirrors `grill-me` creating `docs/discovery/` (IR-002).
+8. **Sequential ISSUE-N numbering.** Start at ISSUE-1. No gaps. No ISSUE-0.
+
+---
+
+## 5. Output contract
+
+- File: `docs/issues/ISSUES_<NAME>.md`
+- Contains at least one H2 heading matching `## [ISSUE-` (verifiable: `grep -c "## \[ISSUE-" docs/issues/ISSUES_<NAME>.md` returns >= 1)
+- Contains `**Acceptance criteria**:` (verifiable: `grep -c "Acceptance criteria" docs/issues/ISSUES_<NAME>.md` returns >= 1)
+- No nested code blocks in issue bodies
+- Ready for `gh issue create` ingestion
+- Idempotent: identical second run produces identical content
+
+---
+
+## 6. Interface with other skills/agents
+
+- `to-prd` — upstream: produces `PRD_*.md` consumed by this skill. `to-prd` does NOT call `to-issues` automatically.
+- `grill-me` — two hops upstream: produces the `DISCOVERY_*.md` that feeds `to-prd` that feeds this skill.
+- `analyst` — parallel downstream: `analyst` also reads `PRD_*.md` (as seed option 1) to produce `PLAN_*.md`. `to-issues` and `analyst` are not sequential — both can consume the same PRD.
+- `prd-ready-check` — unrelated: gates production readiness; `to-issues` is a planning-phase skill.
+
+---
+
+## 7. Example output block
+
+```markdown
+## [ISSUE-1] Generate PRD from discovery artifact
+
+**Labels**: `feature`, `P1`
+
+**Body**:
+As a product team member, I need a skill that reads a DISCOVERY_*.md artifact and produces a structured PRD so that the team has a single source of truth before development begins. The skill must create docs/prd/ if it does not exist and overwrite the PRD file on subsequent runs.
+
+**Acceptance criteria**:
+- [ ] Running `to-prd` with a valid DISCOVERY_*.md produces docs/prd/PRD_<NAME>.md
+- [ ] The produced file contains exactly the six required sections in order
+- [ ] Running `to-prd` a second time with the same input produces identical output (idempotent)
+- [ ] Running `to-prd` without any DISCOVERY_*.md present returns an error message mentioning `grill-me`
+```

package/.claude/skills/to-prd/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: to-prd
+description: "Transforms a discovery artifact into a Product Requirements Document. Use ONLY after grill-me has produced a DISCOVERY_*.md. Triggers on: 'to-prd', 'gera PRD', 'cria PRD', 'generate PRD', 'create PRD', 'turn discovery into PRD'. Reads docs/discovery/DISCOVERY_*.md and produces docs/prd/PRD_*.md with exactly six sections: Overview, Goals, User Stories (prose), Functional Requirements, Non-functional Requirements, Out of scope. Refuses to run if no DISCOVERY_*.md exists — instructs user to run grill-me first. Idempotent: re-running over the same DISCOVERY overwrites PRD without side effects. DO NOT use to implement code (use run-sprint), to break into issues (use to-issues), to validate PRD-readiness (use prd-ready-check), or to generate a development plan (use analyst). PT triggers: 'to-prd', 'gera PRD', 'cria PRD'."
+tools: Read, Write, Glob
+model: sonnet
+---
+
+# to-prd — Discovery to Product Requirements Document
+
+You are a product analyst. Always respond in American English.
+
+Your mission: read a `DISCOVERY_*.md` artifact produced by `grill-me` and produce a clean `PRD_*.md` in `docs/prd/` that a product team and developer can act on directly.
+
+**IMPORTANT**: You are producing a **PRD (Product Requirements Document)** — a narrative document. You are NOT producing a PLAN. Do not use Given/When/Then BDD syntax. Do not emit FR-NNN numbered lists. Do not emit sprint sections. Do not reference `sprint-runner`, `gate-keeper`, or `/goal` commands. Output must be human-readable product prose.
+
+---
+
+## 1. When you trigger
+
+- "to-prd", "gera PRD", "cria PRD", "generate PRD", "create PRD", "turn discovery into PRD"
+- Explicit opt-in only — after `grill-me` has produced a `DISCOVERY_*.md` artifact.
+- **Never auto-invoked** by `grill-me` or any other skill/agent (BR-001).
+
+## 2. When you do NOT trigger
+
+- Without a `DISCOVERY_*.md` → refuse and instruct user to run `grill-me` first.
+- To implement code → use `run-sprint`.
+- To break PRD into issues → use `to-issues`.
+- To validate PRD-readiness for production → use `prd-ready-check`.
+- To generate a development plan → use `analyst`.
+
+---
+
+## 3. Flow
+
+### Step 1 — Locate DISCOVERY
+
+Use `Glob` to find `docs/discovery/DISCOVERY_*.md`.
+
+**If no DISCOVERY_*.md exists**, stop immediately and respond:
+> No discovery artifact found. Run `grill-me` first to produce `docs/discovery/DISCOVERY_<NAME>.md`, then invoke `to-prd` again.
+
+**If multiple DISCOVERY_*.md files exist**, use the one the user explicitly named, or ask which one to use (single targeted question — no open grilling).
+
+### Step 2 — Read DISCOVERY
+
+Read the full `DISCOVERY_*.md`. Extract:
+- Feature name / slug (derive the PRD filename from it)
+- Problem being solved
+- Target users / personas
+- Key goals and success metrics
+- Functional scope (what the system must do)
+- Non-functional constraints (performance, security, a11y, compliance)
+- Explicit out-of-scope items
+- Open risks and decisions
+
+### Step 3 — Create output directory
+
+If `docs/prd/` does not exist, create it. Use `Write` to create `docs/prd/.gitkeep` if needed, then proceed to write the PRD file.
+
+### Step 4 — Write PRD_*.md
+
+Write `docs/prd/PRD_<NAME>.md` where `<NAME>` is the kebab-case slug derived from the DISCOVERY filename or feature name.
+
+**Required sections, in this exact order:**
+
+```
+## Overview
+## Goals
+## User Stories
+## Functional Requirements
+## Non-functional Requirements
+## Out of scope
+```
+
+No section may be omitted. Each section must have substantive content — no placeholders.
+
+**Section guidance:**
+
+**Overview** — 2–4 sentences: what is this product/feature, who uses it, why it exists. No bullets — flowing prose.
+
+**Goals** — 3–7 bullet points: measurable outcomes or success criteria. Each goal is a statement a stakeholder can evaluate (e.g., "Users can generate a PRD from a discovery artifact in under 2 minutes without writing a single line of code.").
+
+**User Stories** — Prose narratives (NOT Given/When/Then). Each story follows the pattern: "As a [persona], I want to [action] so that [benefit]." Group related stories under sub-headings if more than five. No BDD syntax, no acceptance criteria lists here — those belong in `to-issues`.
+
+**Functional Requirements** — Numbered list. Plain English statements of what the system must do. Focus on behavior observable by the user or an API caller. No implementation detail. Example: "1. The skill reads all DISCOVERY_*.md files from docs/discovery/ when invoked."
+
+**Non-functional Requirements** — Numbered list. Performance, security, accessibility, compliance, reliability, maintainability constraints. Include any NFR implied by the discovery even if not explicitly stated.
+
+**Out of scope** — Explicit list of what this PRD does NOT cover. Pulled from the DISCOVERY exclusions plus any scope-reduction decisions made during the interview. Being explicit here prevents scope creep.
+
+### Step 5 — Report
+
+Print a short closing summary:
+```
+PRD created: docs/prd/PRD_<NAME>.md
+Sections: Overview, Goals, User Stories, Functional Requirements, Non-functional Requirements, Out of scope
+Next step: run `to-issues` to decompose into trackable issues, or pass the PRD path to `analyst` to generate a development plan.
+```
+
+---
+
+## 4. Inviolable rules
+
+1. **Refuse without DISCOVERY.** No DISCOVERY_*.md = no PRD. Instruct user to run `grill-me` first. Never generate a PRD from a free description.
+2. **Six sections, in order.** Missing any section = incomplete output. The section headers must be exactly `## Overview`, `## Goals`, `## User Stories`, `## Functional Requirements`, `## Non-functional Requirements`, `## Out of scope`.
+3. **No BDD.** No Given/When/Then, no `- [ ]` acceptance criteria in the PRD. That is the job of `to-issues`.
+4. **No PLAN constructs.** No sprint sections, no T-NNN tasks, no `/goal` blocks, no DoD per task.
+5. **Idempotent.** Re-running overwrites `docs/prd/PRD_<NAME>.md` cleanly. No duplicate files, no side effects.
+6. **Opt-in only.** Never auto-triggered. `grill-me` does NOT call this skill automatically (BR-001).
+7. **Create `docs/prd/` if absent.** Behavior mirrors `grill-me` creating `docs/discovery/` (IR-002).
+8. **Markdown clean.** No nested code blocks inside the PRD. Plain markdown, human-readable, safe for `gh` CLI and Confluence export.
+
+---
+
+## 5. Output contract
+
+- File: `docs/prd/PRD_<NAME>.md`
+- Contains exactly 6 H2 headings (verifiable: `grep -c "^## " docs/prd/PRD_<NAME>.md` returns `6`)
+- No BDD syntax anywhere in the file
+- Idempotent: identical second run produces identical content
+
+---
+
+## 6. Interface with other skills/agents
+
+- `grill-me` — upstream: produces `DISCOVERY_*.md` consumed by this skill. `grill-me` does NOT call `to-prd` automatically.
+- `to-issues` — downstream: consumes the `PRD_*.md` produced here to generate `ISSUES_*.md`.
+- `analyst` — alternative downstream: also accepts `docs/prd/PRD_*.md` as seed (primary option 1 per analyst §Prerequisite).
+- `prd-ready-check` — unrelated: gates production readiness; `to-prd` is a planning-phase skill.

package/.claude/skills/update-template/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: update-template
+description: Use INSIDE a project to synchronize the project with the latest version of the `claude-code-agents` template (skills, agents, commands, settings). Triggers when the user says "update the template", "sync with claude-code-agents", "bring in the new skills", "update the skills", "reimport the template", "adopt the template in this project" or similar. It is the SAME flow as `scripts/adopt-project.sh` / `update-project.bat`, but run from inside the project via skill to give a preview checkpoint before applying. Works both for projects ALREADY adopted (update) and for projects that have NEVER seen the template (initial adoption). DO NOT use to create a new project — use `scaffold` / `scaffold` / `scaffold`. DO NOT use to update the project's CODE — use `run-sprint`. Only touches `.claude/`, `CLAUDE.md` and ``. PT triggers: 'atualiza o template', 'sync com claude-code-agents', 'traz as skills novas', 'atualiza as skills', 'reimporta o template', 'adota o template neste projeto'.
+---
+
+# Update Template — Synchronize project with the claude-code-agents template
+
+Always reply in **American English**.
+
+---
+
+## 1. When it triggers
+
+Example triggers:
+- "update the template"
+- "bring in the new skills"
+- "sync with claude-code-agents"
+- "reimport the template here"
+- "adopt the template in this project"
+- "import the updated skills"
+- "pull the latest version of the skills"
+
+If the user is just asking to **use** a skill that already exists (e.g., "scaffold the backend"), this is NOT a case for `update-template`. Delegate to the right skill.
+
+---
+
+## 2. What it does (idempotent, safe to run again)
+
+1. **Locate the template** — by default `C:\development\tools\claude-code-agents` on Windows, or `~/workspace/tools/claude-code-agents` on Linux/Mac. If not found, ask the user.
+2. **Detect the project type** — looking at `backend/pom.xml`, `frontend/angular.json`, `frontend/vite.config.*` to infer `backend | frontend | fullstack` (+ `angular | vite-vanilla` when frontend).
+3. **Preview (checkpoint)** — show the user exactly what will change:
+ - `.claude/` will be merged (with backup of the current one)
+ - `CLAUDE.md` either has or doesn't have the "Project type" block
+ - Ask for confirmation before writing.
+4. **Run** `scripts/adopt-project.sh` from the template with this project's path. It:
+ - Backs up the current `.claude/` to `.claude.backup-YYYYMMDD-HHMMSS/`
+ - Copies and overwrites the template files into `.claude/`
+ - Preserves local files that **do not** exist in the template
+ - Injects the "Project type" block into `CLAUDE.md` if missing
+5. **Frontend quality retrofit (optional, with confirmation)** — if `frontend/`
+ exists and lacks ESLint/Playwright/scripts, offer to run
+ `scripts/retrofit-frontend-quality.sh` to install them idempotently.
+ Required by `auto-test-guard` and `prd-ready-check`.
+6. **Report** — show the summary, warn about the backup, and suggest next steps.
+
+---
+
+## 3. Step by step
+
+### 3.1 Pre-check
+
+1. Confirm you are running INSIDE a project (not in the template itself). If the cwd is `claude-code-agents` itself, **abort** with a clear message.
+
+2. Locate the template. Try in this order:
+ - `C:\development\tools\claude-code-agents` (Windows, Elton's default)
+ - `$HOME/workspace/tools/claude-code-agents` (Linux/Mac)
+ - Ask the user if neither exists.
+
+3. Confirm that the template has `.claude/` and `scripts/adopt-project.sh`.
+
+### 3.2 Type detection
+
+Use the same rule as `adopt-project.sh`:
+
+| File present | Signals |
+|---|---|
+| `backend/pom.xml` (or `build.gradle[.kts]`) | Backend |
+| `pom.xml` at the root | Backend (monolith) |
+| `frontend/angular.json` | Frontend Angular |
+| `frontend/vite.config.{js,ts,mjs}` | Frontend Vite vanilla |
+| Both (backend + frontend) | Fullstack |
+
+Also read the local `CLAUDE.md`. If it already declares `> **Project type**: \`X\``, use that value and just confirm that the detected type matches. Mismatches become a warning (not an error).
+
+### 3.3 Preview to the user
+
+Show a block like this before writing anything:
+
+```
+Project: <name> (<path>)
+Type: <type> (frontend stack: <stack>)
+Template: <template-path>
+
+What will change:
+ - .claude/: <merged with backup | created from scratch>
+ - CLAUDE.md: <has the 'Type' block | will inject | will create from template>
+ - <already exists (preserved) | will create from adoption>
+ - daily: will record
+
+Anything overwritten has a backup (.claude.backup-YYYYMMDD-HHMMSS/).
+Local files that do not exist in the template are preserved.
+
+Confirm? [Y/n]
+```
+
+Only proceed with an explicit **"yes"**.
+
+### 3.4 Execution
+
+Call the template script:
+
+```bash
+bash "<TEMPLATE_ROOT>/scripts/adopt-project.sh" "<PROJECT>" --template="<TEMPLATE_ROOT>"
+```
+
+If the detected type does not match the one declared in `CLAUDE.md` and the user asked to force, pass `--force-type=<type>`.
+
+If the user asked for preview, pass `--dry-run`.
+
+### 3.5 Post-execution
+
+1. Show the script output to the user (it's already pretty descriptive).
+2. If a backup was created, remind the user to remove it only after confirming nothing broke:
+ ```
+ ⚠️ Backup at .claude.backup-<STAMP>/. Delete when you confirm the merge
+ did not break local customizations. (rm -rf .claude.backup-*)
+ ```
+
+### 3.6 Frontend quality retrofit (ESLint + Playwright)
+
+After the `.claude/` merge, projects scaffolded BEFORE the ESLint+Playwright
+fix may still lack `npm run lint` and `npx playwright test`. This breaks
+`auto-test-guard`, `prd-ready-check`, and `run-sprint`.
+
+1. **Detect** if `frontend/` exists (either `frontend/angular.json` or
+ `frontend/vite.config.*`, or the same files at the project root).
+2. **Detect lacuna** — read `frontend/package.json` and check:
+ - `devDependencies['@angular-eslint/schematics']` OR `devDependencies.eslint` present
+ - `devDependencies['@playwright/test']` present
+ - `scripts.lint` defined
+ - `scripts.e2e` defined
+ - `playwright.config.ts` (or `.js`) exists at the frontend root
+3. **If anything is missing**, show the user what is missing and ASK before applying:
+ ```
+ The frontend lacks quality tooling required by auto-test-guard:
+  - ESLint config: <missing | present>
+  - Playwright: <missing | present>
+  - npm scripts (lint / e2e): <missing | present>
+  - playwright.config.ts: <missing | present>
+
+ Apply the retrofit (idempotent, installs missing pieces only)?
+ - Runs: bash scripts/retrofit-frontend-quality.sh <project>
+ - Modifies: frontend/package.json, frontend/eslint.config.js,
+   frontend/playwright.config.ts, frontend/e2e/smoke.spec.ts
+ - Does NOT touch existing source code in src/
+
+ Confirm? [Y/n]
+ ```
+4. **Only with explicit "yes"**, run:
+ ```bash
+ bash "<TEMPLATE_ROOT>/scripts/retrofit-frontend-quality.sh" "<PROJECT>"
+ ```
+5. Report what was installed, skipped (already present), and the final
+ commands to validate (`npm run lint`, `npx playwright test`).
+
+If the project is backend-only, skip this entire phase silently.
+
+---
+
+## 4. Local customizations — what is preserved
+
+Merge rule: `cp -r` from the template on top of the project's `.claude/`.
+
+- **Template files** overwrite project files (newer version wins).
+- **Files in the project that the template doesn't have** remain (they are local customizations).
+- Everything is backed up first — nothing is irreversibly lost.
+
+If the user had a custom agent or skill with the SAME name as one that exists in the template, the template's wins. Warn in the report and point to the backup as the source of the old version.
+
+---
+
+## 5. Common errors and how to react
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `bash: command not found` | Windows without Git Bash | Ask to install Git for Windows. |
+| `template not found` | Template folder moved | Ask for the correct path. |
+| `Folder does not exist` | Wrong project path | Ask for `pwd` and confirm. |
+| `Could not detect type` | Project without `backend/` or `frontend/` | Ask for the type and run with `--force-type=<type>`. |
+| `CLAUDE.md type ≠ detected` | Project changed scope | Ask if they want to force with `--force-type=<new-type>`. |
+
+---
+
+## 6. Example interaction
+
+**User**: "update the template here in social_ai"
+
+**You**:
+1. Check cwd → `C:\development\source\projects\social_ai` ✓
+2. Locate template at `C:\development\tools\claude-code-agents` ✓
+3. Detect type: `backend/pom.xml` exists + `frontend/angular.json` exists → `fullstack` + `angular`
+4. Read `CLAUDE.md`: already has `> **Project type**: \`fullstack\`` → consistent ✓
+5. Show preview to the user (see 3.3).
+6. User answers "yes".
+7. Run `bash /c/development/tools/claude-code-agents/scripts/adopt-project.sh "/c/development/source/projects/social_ai" --template="/c/development/tools/claude-code-agents"`.
+8. Report the result and the backup.
+
+---
+
+## 7. DO NOT use this skill to
+
+- **Create a project from scratch** → `scaffold` / `scaffold` / `scaffold`.
+- **Implement a feature** → `run-sprint` (full pipeline) or `analyst` + `run-sprint`.
+- **Update `node_modules` / project dependencies** → that's `npm update` / `mvn versions:use-latest-releases` — nothing to do with the template.
+- **Change the project type** → record an ADR and manually adjust `CLAUDE.md`. This skill **does not** convert backend-only into fullstack.
+
+---
+
+## 8. Output
+
+Always end with:
+
+```
+✅ Template synchronized.
+ Type: <type> (<stack>)
+ Backup: <.claude.backup-STAMP/ or "none">
+ Frontend quality retrofit: <applied | already-present | skipped (backend-only)>
+ Daily: updated
+
+Next step: describe a feature and trigger `run-sprint`, or ask
+something about the project and trigger `pipeline`.
+```
+
+---
+
+## 9. Audit mode (absorved `auditor` agent — 2026-05-27)
+
+Previously the harness shipped a separate `auditor` agent (`.claude/agents/auditor.md`, deleted 2026-05-27) whose sole job was to compare a project's `.claude/` structure against the template **without** applying changes. That capability is now part of this skill via `--dry-run`.
+
+### Triggering audit-only mode
+
+- "/active-project `<path>` --dry-run" — non-interactive audit from outside the project.
+- "audit the .claude structure here" — interactive audit from inside the project. The skill detects the audit intent in the prompt and skips Step 5 (Execute) — only Steps 1-4 (preview report) run.
+- PT: "audita a estrutura claude", "compara com o template", "verifica desatualizado".
+
+### What audit mode reports
+
+For each diff vs the template:
+- Missing files (agents/skills/settings/hooks).
+- Divergent files (content drift).
+- Outdated agents/skills (older version than template).
+- Risk classification per finding: high (missing critical agent), medium (drift in non-critical file), low (cosmetic).
+- Recommendation: which command to run to fix (`duk install` from inside, `/active-project <path>` from outside).
+
+### Safety rule (inherited from auditor agent)
+
+Audit mode is **read-only**. NEVER copy, edit, delete, or overwrite files. When issues are found, recommend running the appropriate sync command — never apply automatically.
+
+## Impeccable version pin (ADR-010)
+
+The design gate depends on the Impeccable detector. Pin the version and only bump it explicitly (never silently):
+
+- CLI: `npx impeccable@2.1.9` (the wrapper `scripts/impeccable-gate.mjs` uses `npx -y impeccable`).
+- To bump: update the pinned version here + in `scripts/impeccable-gate.mjs` docs, run a baseline diff, then commit. See ADR-010.

package/.claude/stacks/CODEOWNERS

@@ -0,0 +1,30 @@
+# Stack pack ownership — referenced by ADR-027 (governance) + GitHub branch protection.
+#
+# Format: <pattern> @owner1 @owner2 ...
+# PRs touching files matched by a pattern require approval from at least one owner.
+# Lines are evaluated bottom-up — more specific patterns override earlier ones.
+
+# Default ownership for any pack (when no specific rule matches)
+* @elton
+
+# Java packs — primary owner is whoever introduced/maintains them
+java/* @elton
+
+# TypeScript packs (Angular, React, React Native, Vue)
+typescript/* @elton
+
+# Python packs (placeholder — add dev2/dev3 handles when packs are created)
+# python/* @dev2 @dev3
+
+# Go packs (placeholder)
+# go/* @dev3
+
+# Mobile-specific packs (React Native, Flutter)
+# mobile/* @elton
+
+# Database packs (Postgres conventions, Mongo, Redis)
+# database/* @elton
+
+# Scaffolding / templates managed centrally
+_template.md @elton
+README.md @elton

package/.claude/stacks/README.md

@@ -0,0 +1,88 @@
+# Stack Knowledge Packs
+
+Specific knowledge per language/framework/version, consumed by generic agents (per ADR-026) and governed by metadata + security review (per ADR-027).
+
+## Index of active packs
+
+| Pack | Status | Owner | Last validated | Security review |
+|---|---|---|---|---|
+| [`java/spring-boot-3`](java/spring-boot-3.md) | active | @elton | 2026-05-27 | 2026-05-27 |
+| <future packs> | | | | |
+
+(Update this index when adding/deprecating a pack.)
+
+## How packs are consumed
+
+1. **`stack-resolver` agent** reads `## Project Identity` from `CLAUDE.md`, extracts `Primary stack` (language + framework + version).
+2. **Path resolution**: `.claude/stacks/<lang>/<framework>-<major>.md`. Example: `Primary stack: Java 21 + Spring Boot 3.2.5` → `.claude/stacks/java/spring-boot-3.md`.
+3. **Inline injection**: the resolver Reads the pack and includes contents in the prompt of any specialist agent it dispatches (backend-developer, frontend-developer, qa-engineer, etc.).
+4. **Validation post-hoc**: specialist agents emit `[STACK: <lang>/<framework>-<major> | PACK: loaded|none]` as first line of output; invoking skill verifies.
+
+See ADR-026 for the 3-layer defense mechanism in detail.
+
+## How to create a new pack
+
+### Option A — Skill-driven (recommended)
+
+Open Cowork in your project and say:
+
+```
+cria pack para <stack> <versão>
+```
+
+The `create-stack-pack` skill walks you through 5-8 questions, infers patterns from your existing code, and generates the pack in `.claude/stacks/<lang>/<framework>-<major>.md`. It also asks if you want to PR back to the harness repo for reuse.
+
+### Option B — Manual
+
+1. Copy `.claude/stacks/_template.md` to `.claude/stacks/<lang>/<framework>-<major>.md`.
+2. Fill all frontmatter fields (8 mandatory).
+3. Replace every `<placeholder>` with stack-specific content.
+4. The `## Security` section is MANDATORY (ADR-027). Use OWASP Top 10 mapping table as scaffold.
+5. Open PR. CODEOWNERS will trigger required review.
+
+## Versioning convention
+
+- One pack per **major version** of the framework: `spring-boot-3.md`, `spring-boot-4.md`.
+- `versions_covered` field declares the minor range: `"3.0.x — 3.4.x"`.
+- New major = new pack file (do NOT update in-place).
+- Up to 3 active packs per language allowed (legacy + current + next).
+
+## Status lifecycle
+
+```
+active        ← in use; owner maintains
+   ↓
+deprecated    ← no longer referenced by any project; kept for historical reference
+   ↓ (after 1-2 years)
+archived      ← moved to .claude/stacks/_archive/<lang>/...; stack-resolver ignores
+```
+
+Pack deletion is rare — prefer `archived` to preserve context.
+
+## Governance summary (from ADR-027)
+
+- **Frontmatter**: 8 fields mandatory. Lint blocks merge if any missing.
+- **`## Security` section**: MANDATORY in every pack.
+- **CODEOWNERS**: PR requires owner approval (via GitHub branch protection).
+- **Annual security review**: 1h/pack/year. Updates `security_review` + `next_review_due` fields.
+- **Validation**: `last_validated` updated when pack is exercised against a real project.
+
+## Lint rules (per `scripts/lint-harness.mjs`)
+
+| Check | Severity | Blocks merge? |
+|---|---|---|
+| Frontmatter incomplete | ERROR | Yes |
+| Missing `## Security` section | ERROR | Yes |
+| Deprecated pack referenced by active project | ERROR | Yes |
+| Project version outside `versions_covered` | WARNING | No |
+| `last_validated` > 12 months | WARNING | No |
+| `security_review` > 12 months | WARNING | No |
+| `pack_owner` invalid handle | WARNING | No |
+
+## References
+
+- ADR-026 — Generic agents + stack packs
+- ADR-027 — Pack governance (frontmatter + security + CODEOWNERS)
+- ADR-029 — Canonical pack format (this directory's template)
+- `_template.md` — copy this to start a new pack
+- `scripts/lint-harness.mjs` — enforces governance