[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M784VC2S7TKFTT5JX0Y8N59M":3,"skill-same:01M784VC2S7TKFTT5JX0Y8N59M":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":31,"ownerHtmlUrl":32,"ownerBlogUrl":6,"ownerDescription":33,"updatedAt":34,"install":35,"resources":47},"01M784VC2S7TKFTT5JX0Y8N59M","adr-skill",null,"Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept\u002Freject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.","Lord1Egypt\u002Fawesome-skill-forge","Lord1Egypt","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F99746359?v=4","01M7592YDNT0XK9WJ0T2MQVPDN","Mohamed Mounir Ali AL Keshita","01M75GRFNHC8VZNWEB8DKDE433",3,"MIT","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fcommunity\u002Fskills_sh\u002Fs\u002Fskills-sh_vercel_ai_adr-skill\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: adr-skill\ndescription: Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept\u002Freject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.\nmetadata:\n  internal: true\n---\n\n# ADR Skill\n\n## Philosophy\n\nADRs created with this skill are **executable specifications for coding agents**. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.\n\nThis means:\n\n- Constraints must be explicit and measurable, not vibes\n- Decisions must be specific enough to act on (\"use PostgreSQL 16 with pgvector\" not \"use a database\")\n- Consequences must map to concrete follow-up tasks\n- Non-goals must be stated to prevent scope creep\n- The ADR must be self-contained — no tribal knowledge assumptions\n- **The ADR must include an implementation plan** — which files to touch, which patterns to follow, which tests to write, and how to verify the decision was implemented correctly\n\n## When to Write an ADR\n\nWrite an ADR when a decision:\n\n- **Changes how the system is built or operated** (new dependency, architecture pattern, infrastructure choice, API design)\n- **Is hard to reverse** once code is written against it\n- **Affects other people or agents** who will work in this codebase later\n- **Has real alternatives** that were considered and rejected\n\nDo NOT write an ADR for:\n\n- Routine implementation choices within an established pattern\n- Bug fixes or typo corrections\n- Decisions already captured in an existing ADR (update it instead)\n- Style preferences already covered by linters or formatters\n\nWhen in doubt: if a future agent working in this codebase would benefit from knowing _why_ this choice was made, write the ADR.\n\n### Proactive ADR Triggers (For Agents)\n\nIf you are an agent coding in a repo and you encounter any of these situations, **stop and propose an ADR** before continuing:\n\n- You are about to introduce a new dependency that doesn't already exist in the project\n- You are about to create a new architectural pattern (new way of handling errors, new data access layer, new API convention) that other code will need to follow\n- You are about to make a choice between two or more real alternatives and the tradeoffs are non-obvious\n- You are about to change something that contradicts an existing accepted ADR\n- You realize you're writing a long code comment explaining \"why\" — that reasoning belongs in an ADR\n\n**How to propose**: Tell the human what decision you've hit, why it matters, and ask if they want to capture it as an ADR. If yes, run the full four-phase workflow. If no, note the decision in a code comment and move on.\n\n## Creating an ADR: Four-Phase Workflow\n\nEvery ADR goes through four phases. Do not skip phases.\n\n### Phase 0: Scan the Codebase\n\nBefore asking any questions, gather context from the repo:\n\n1. **Find existing ADRs.** Check `contributing\u002Fdecisions\u002F`, `docs\u002Fdecisions\u002F`, `adr\u002F`, `docs\u002Fadr\u002F`, `decisions\u002F` for existing records. Read them. Note:\n   - Existing conventions (directory, naming, template style)\n   - Decisions that relate to or constrain the current one\n   - Any ADRs this new decision might supersede\n\n2. **Check the tech stack.** Read `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, or equivalent. Note relevant dependencies and versions.\n\n3. **Find related code patterns.** If the decision involves a specific area (e.g., \"how we handle auth\"), scan for existing implementations. Identify the specific files, directories, and patterns that will be affected by the decision.\n\n4. **Check for ADR references in code.** Look for ADR references in comments and docs (see \"Code ↔ ADR Linking\" below). This reveals which existing decisions govern which parts of the codebase.\n\n5. **Note what you found.** Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.\n\n### Phase 1: Capture Intent (Socratic)\n\nInterview the human to understand the decision space. Ask questions **one at a time**, building on previous answers. Do not dump a list of questions.\n\n**Core questions** (ask in roughly this order, skip what's already clear from context or Phase 0):\n\n1. **What are you deciding?** — Get a short, specific title. Push for a verb phrase (\"Choose X\", \"Adopt Y\", \"Replace Z with W\").\n2. **Why now?** — What broke, what's changing, or what will break if you do nothing? This is the trigger.\n3. **What constraints exist?** — Tech stack, timeline, budget, team size, existing code, compliance. Be concrete. Reference what you found in Phase 0 (\"I see you're already using X — does that constrain this?\").\n4. **What does success look like?** — Measurable outcomes. Push past \"it works\" to specifics (latency, throughput, DX, maintenance burden).\n5. **What options have you considered?** — At least two. For each: what's the core tradeoff? If they only have one option, help them articulate why alternatives were rejected.\n6. **What's your current lean?** — Capture gut intuition early. Often reveals unstated priorities.\n7. **Who needs to know or approve?** — Decision-makers, consulted experts, informed stakeholders.\n8. **What would an agent need to implement this?** — Which files\u002Fdirectories are affected? What existing patterns should it follow? What should it avoid? What tests would prove it's working? This directly feeds the Implementation Plan.\n\n**Adaptive follow-ups**: Based on answers, probe deeper where the decision is fuzzy. Common follow-ups:\n\n- \"What's the worst-case outcome if this decision is wrong?\"\n- \"What would make you revisit this in 6 months?\"\n- \"Is there anything you're explicitly choosing NOT to do?\"\n- \"What prior art or existing patterns in the codebase does this relate to?\"\n- \"I found [existing ADR\u002Fpattern] — does this new decision interact with it?\"\n\n**When to stop**: You have enough when you can fill every section of the ADR — including the Implementation Plan — without making things up. If you're guessing at any section, ask another question.\n\n**Intent Summary Gate**: Before moving to Phase 2, present a structured summary of what you captured and ask the human to confirm or correct it:\n\n> **Here's what I'm capturing for the ADR:**\n>\n> - **Title**: {title}\n> - **Trigger**: {why now}\n> - **Constraints**: {list}\n> - **Options**: {option 1} vs {option 2} [vs ...]\n> - **Lean**: {which option and why}\n> - **Non-goals**: {what's explicitly out of scope}\n> - **Related ADRs\u002Fcode**: {what exists that this interacts with}\n> - **Affected files\u002Fareas**: {where in the codebase this lands}\n> - **Verification**: {how we'll know it's implemented correctly}\n>\n> **Does this capture your intent? Anything to add or correct?**\n\nDo NOT proceed to Phase 2 until the human confirms the summary.\n\n### Phase 2: Draft the ADR\n\n1. **Choose the ADR directory.**\n   - If one exists (found in Phase 0), use it.\n   - If none exists, create `contributing\u002Fdecisions\u002F` (if `contributing\u002F` exists), `docs\u002Fdecisions\u002F` (MADR default), or `adr\u002F` (simpler repos).\n\n2. **Choose a filename strategy.**\n   - If existing ADRs use date prefixes (`YYYY-MM-DD-...`), continue that.\n   - Otherwise use slug-only filenames (`choose-database.md`).\n\n3. **Choose a template.**\n   - Use `assets\u002Ftemplates\u002Fadr-simple.md` for straightforward decisions (one clear winner, minimal tradeoffs).\n   - Use `assets\u002Ftemplates\u002Fadr-madr.md` when you need to document multiple options with structured pros\u002Fcons\u002Fdrivers.\n   - See `references\u002Ftemplate-variants.md` for guidance.\n\n4. **Fill every section from the confirmed intent summary.** Do not leave placeholder text. Every section should contain real content or be removed (optional sections only).\n\n5. **Write the Implementation Plan.** This is the most important section for agent-first ADRs. It tells the next agent exactly what to do. See the template for structure.\n\n6. **Write Verification criteria as checkboxes.** These must be specific enough that an agent can programmatically or manually check each one.\n\n7. **Generate the file.**\n   - Preferred: run `scripts\u002Fnew_adr.js` (handles directory, naming, and optional index updates).\n   - If you can't run scripts, copy a template from `assets\u002Ftemplates\u002F` and fill it manually.\n\n### Phase 3: Review Against Checklist\n\nAfter drafting, review the ADR against the agent-readiness checklist in `references\u002Freview-checklist.md`.\n\n**Present the review as a summary**, not a raw checklist dump. Format:\n\n> **ADR Review**\n>\n> ✅ **Passes**: {list what's solid — e.g., \"context is self-contained, implementation plan covers affected files, verification criteria are checkable\"}\n>\n> ⚠️ **Gaps found**:\n>\n> - {specific gap 1 — e.g., \"Implementation Plan doesn't mention test files — which test suite should cover this?\"}\n> - {specific gap 2}\n>\n> **Recommendation**: {Ship it \u002F Fix the gaps first \u002F Needs more Phase 1 work}\n\nOnly surface failures and notable strengths — do not recite every passing checkbox.\n\nIf there are gaps, propose specific fixes. Do not just flag problems — offer solutions and ask the human to approve.\n\nDo not finalize until the ADR passes the checklist or the human explicitly accepts the gaps.\n\n## Consulting ADRs (Read Workflow)\n\nAgents should read existing ADRs **before implementing changes** in a codebase that has them. This is not part of the create-an-ADR workflow — it's a standalone operation any agent should do.\n\n### When to Consult ADRs\n\n- Before starting work on a feature that touches architecture (auth, data layer, API design, infrastructure)\n- When you encounter a pattern in the code and wonder \"why is it done this way?\"\n- Before proposing a change that might contradict an existing decision\n- When a human says \"check the ADRs\" or \"there's a decision about this\"\n- When you find an ADR reference in a code comment\n\n### How to Consult ADRs\n\n1. **Find the ADR directory.** Check `contributing\u002Fdecisions\u002F`, `docs\u002Fdecisions\u002F`, `adr\u002F`, `docs\u002Fadr\u002F`, `decisions\u002F`. Also check for an index file (`README.md` or `index.md`).\n\n2. **Scan titles and statuses.** Read the index or list filenames. Focus on `accepted` ADRs — these are active decisions.\n\n3. **Read relevant ADRs fully.** Don't just read the title — read context, decision, consequences, non-goals, AND the Implementation Plan. The Implementation Plan tells you what patterns to follow and what files are governed by this decision.\n\n4. **Respect the decisions.** If an accepted ADR says \"use PostgreSQL,\" don't propose switching to MongoDB without creating a new ADR that supersedes it. If you find a conflict between what the code does and what the ADR says, flag it to the human.\n\n5. **Follow the Implementation Plan.** When implementing code in an area governed by an ADR, follow the patterns specified in its Implementation Plan. If the plan says \"all new queries go through the data-access layer in `src\u002Fdb\u002F`,\" do that.\n\n6. **Reference ADRs in your work.** Add ADR references in code comments and PR descriptions (see \"Code ↔ ADR Linking\" below).\n\n## Code ↔ ADR Linking\n\nADRs should be bidirectionally linked to the code they govern.\n\n### ADR → Code (in the Implementation Plan)\n\nThe Implementation Plan section names specific files, directories, and patterns:\n\n```markdown\n## Implementation Plan\n\n- **Affected paths**: `src\u002Fdb\u002F`, `src\u002Fconfig\u002Fdatabase.ts`, `tests\u002Fintegration\u002F`\n- **Pattern**: all database queries go through `src\u002Fdb\u002Fclient.ts`\n```\n\n### Code → ADR (in comments)\n\nWhen implementing code guided by an ADR, add a comment referencing it:\n\n```typescript\n\u002F\u002F ADR: Using better-sqlite3 for test database\n\u002F\u002F See: docs\u002Fdecisions\u002F2025-06-15-use-sqlite-for-test-database.md\nimport Database from 'better-sqlite3';\n```\n\nKeep these lightweight — one comment at the entry point, not on every line. The goal is discoverability: when a future agent reads this code, they can find the reasoning.\n\n### Why This Matters\n\n- An agent working in `src\u002Fdb\u002F` can find which ADRs govern that area\n- An agent reading an ADR can find the code that implements it\n- When an ADR is superseded, the code references make it easy to find all code that needs updating\n\n## Other Operations\n\n### Update an Existing ADR\n\n1. Identify the intent:\n   - **Accept \u002F reject**: change status, add any final context.\n   - **Deprecate**: status → `deprecated`, explain replacement path.\n   - **Supersede**: create a new ADR, link both ways (old → new, new → old).\n   - **Add learnings**: append to `## More Information` with a date stamp. Do not rewrite history.\n\n2. Use `scripts\u002Fset_adr_status.js` for status changes (supports YAML front matter, bullet status, and section status).\n\n### Post-Acceptance Lifecycle\n\nAfter an ADR is accepted:\n\n1. **Create implementation tasks.** Each item in the Implementation Plan and each follow-up in Consequences should become a trackable task (issue, ticket, or TODO).\n2. **Reference the ADR in PRs.** Link to the ADR in PR descriptions, e.g. \"Implements `contributing\u002Fdecisions\u002F2025-06-15-use-sqlite-for-test-database.md`.\"\n3. **Add code references.** Add ADR path comments at key implementation points.\n4. **Check verification criteria.** Once implementation is complete, walk through the Verification checkboxes. Update the ADR with results in `## More Information`.\n5. **Revisit when triggers fire.** If the ADR specified revisit conditions (\"if X happens, reconsider\"), monitor for those conditions.\n\n### Index\n\nIf the repo has an ADR index\u002Flog file (often `README.md` or `index.md` in the ADR dir), keep it updated.\n\nPreferred: let `scripts\u002Fnew_adr.js --update-index` do it. Otherwise:\n\n- Add a bullet entry for the new ADR.\n- Keep ordering consistent (numeric if numbered; date or alpha if slugs).\n\n### Bootstrap\n\nWhen introducing ADRs to a repo that has none:\n\n```bash\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fbootstrap_adr.js\n```\n\nThis creates the directory, an index file, and a filled-out first ADR (\"Adopt architecture decision records\") with real content explaining why the team is using ADRs. Use `--json` for machine-readable output. Use `--dir` to override the directory name.\n\n### Categories (Large Projects)\n\nFor repos with many ADRs, organize by subdirectory:\n\n```\ndocs\u002Fdecisions\u002F\n  backend\u002F\n    2025-06-15-use-postgres.md\n  frontend\u002F\n    2025-06-20-use-react.md\n  infrastructure\u002F\n    2025-07-01-use-terraform.md\n```\n\nDate prefixes are local to each category. Choose a categorization scheme early (by layer, by domain, by team) and document it in the index.\n\n## Resources\n\n### scripts\u002F\n\n- `scripts\u002Fnew_adr.js` — create a new ADR file from a template, using repo conventions.\n- `scripts\u002Fset_adr_status.js` — update an ADR status in-place (YAML front matter or inline). Use `--json` for machine output.\n- `scripts\u002Fbootstrap_adr.js` — create ADR dir, `README.md`, and initial \"Adopt ADRs\" decision.\n\n### references\u002F\n\n- `references\u002Freview-checklist.md` — agent-readiness checklist for Phase 3 review.\n- `references\u002Fadr-conventions.md` — directory, filename, status, and lifecycle conventions.\n- `references\u002Ftemplate-variants.md` — when to use simple vs MADR-style templates.\n- `references\u002Fexamples.md` — filled-out short and long ADR examples with implementation plans.\n\n### assets\u002F\n\n- `assets\u002Ftemplates\u002Fadr-simple.md` — lean template for straightforward decisions.\n- `assets\u002Ftemplates\u002Fadr-madr.md` — MADR 4.0 template for decisions with multiple options and structured tradeoffs.\n- `assets\u002Ftemplates\u002Fadr-readme.md` — default ADR index scaffold used by `scripts\u002Fbootstrap_adr.js`.\n\n### Script Usage\n\nFrom the target repo root:\n\n```bash\n# Simple ADR\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fnew_adr.js --title \"Choose database\" --status proposed\n\n# MADR-style with options\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fnew_adr.js --title \"Choose database\" --template madr --status proposed\n\n# With index update\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fnew_adr.js --title \"Choose database\" --status proposed --update-index\n\n# Bootstrap a new repo\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fbootstrap_adr.js --dir docs\u002Fdecisions\n```\n\nNotes:\n\n- Scripts auto-detect ADR directory and filename strategy.\n- Use `--dir` and `--strategy` to override.\n- Use `--json` to emit machine-readable output.\n","# ADR Skill\n\n## Philosophy\n\nADRs created with this skill are **executable specifications for coding agents**. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.\n\nThis means:\n\n- Constraints must be explicit and measurable, not vibes\n- Decisions must be specific enough to act on (\"use PostgreSQL 16 with pgvector\" not \"use a database\")\n- Consequences must map to concrete follow-up tasks\n- Non-goals must be stated to prevent scope creep\n- The ADR must be self-contained — no tribal knowledge assumptions\n- **The ADR must include an implementation plan** — which files to touch, which patterns to follow, which tests to write, and how to verify the decision was implemented correctly\n\n## When to Write an ADR\n\nWrite an ADR when a decision:\n\n- **Changes how the system is built or operated** (new dependency, architecture pattern, infrastructure choice, API design)\n- **Is hard to reverse** once code is written against it\n- **Affects other people or agents** who will work in this codebase later\n- **Has real alternatives** that were considered and rejected\n\nDo NOT write an ADR for:\n\n- Routine implementation choices within an established pattern\n- Bug fixes or typo corrections\n- Decisions already captured in an existing ADR (update it instead)\n- Style preferences already covered by linters or formatters\n\nWhen in doubt: if a future agent working in this codebase would benefit from knowing _why_ this choice was made, write the ADR.\n\n### Proactive ADR Triggers (For Agents)\n\nIf you are an agent coding in a repo and you encounter any of these situations, **stop and propose an ADR** before continuing:\n\n- You are about to introduce a new dependency that doesn't already exist in the project\n- You are about to create a new architectural pattern (new way of handling errors, new data access layer, new API convention) that other code will need to follow\n- You are about to make a choice between two or more real alternatives and the tradeoffs are non-obvious\n- You are about to change something that contradicts an existing accepted ADR\n- You realize you're writing a long code comment explaining \"why\" — that reasoning belongs in an ADR\n\n**How to propose**: Tell the human what decision you've hit, why it matters, and ask if they want to capture it as an ADR. If yes, run the full four-phase workflow. If no, note the decision in a code comment and move on.\n\n## Creating an ADR: Four-Phase Workflow\n\nEvery ADR goes through four phases. Do not skip phases.\n\n### Phase 0: Scan the Codebase\n\nBefore asking any questions, gather context from the repo:\n\n1. **Find existing ADRs.** Check `contributing\u002Fdecisions\u002F`, `docs\u002Fdecisions\u002F`, `adr\u002F`, `docs\u002Fadr\u002F`, `decisions\u002F` for existing records. Read them. Note:\n   - Existing conventions (directory, naming, template style)\n   - Decisions that relate to or constrain the current one\n   - Any ADRs this new decision might supersede\n\n2. **Check the tech stack.** Read `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, or equivalent. Note relevant dependencies and versions.\n\n3. **Find related code patterns.** If the decision involves a specific area (e.g., \"how we handle auth\"), scan for existing implementations. Identify the specific files, directories, and patterns that will be affected by the decision.\n\n4. **Check for ADR references in code.** Look for ADR references in comments and docs (see \"Code ↔ ADR Linking\" below). This reveals which existing decisions govern which parts of the codebase.\n\n5. **Note what you found.** Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.\n\n### Phase 1: Capture Intent (Socratic)\n\nInterview the human to understand the decision space. Ask questions **one at a time**, building on previous answers. Do not dump a list of questions.\n\n**Core questions** (ask in roughly this order, skip what's already clear from context or Phase 0):\n\n1. **What are you deciding?** — Get a short, specific title. Push for a verb phrase (\"Choose X\", \"Adopt Y\", \"Replace Z with W\").\n2. **Why now?** — What broke, what's changing, or what will break if you do nothing? This is the trigger.\n3. **What constraints exist?** — Tech stack, timeline, budget, team size, existing code, compliance. Be concrete. Reference what you found in Phase 0 (\"I see you're already using X — does that constrain this?\").\n4. **What does success look like?** — Measurable outcomes. Push past \"it works\" to specifics (latency, throughput, DX, maintenance burden).\n5. **What options have you considered?** — At least two. For each: what's the core tradeoff? If they only have one option, help them articulate why alternatives were rejected.\n6. **What's your current lean?** — Capture gut intuition early. Often reveals unstated priorities.\n7. **Who needs to know or approve?** — Decision-makers, consulted experts, informed stakeholders.\n8. **What would an agent need to implement this?** — Which files\u002Fdirectories are affected? What existing patterns should it follow? What should it avoid? What tests would prove it's working? This directly feeds the Implementation Plan.\n\n**Adaptive follow-ups**: Based on answers, probe deeper where the decision is fuzzy. Common follow-ups:\n\n- \"What's the worst-case outcome if this decision is wrong?\"\n- \"What would make you revisit this in 6 months?\"\n- \"Is there anything you're explicitly choosing NOT to do?\"\n- \"What prior art or existing patterns in the codebase does this relate to?\"\n- \"I found [existing ADR\u002Fpattern] — does this new decision interact with it?\"\n\n**When to stop**: You have enough when you can fill every section of the ADR — including the Implementation Plan — without making things up. If you're guessing at any section, ask another question.\n\n**Intent Summary Gate**: Before moving to Phase 2, present a structured summary of what you captured and ask the human to confirm or correct it:\n\n> **Here's what I'm capturing for the ADR:**\n>\n> - **Title**: {title}\n> - **Trigger**: {why now}\n> - **Constraints**: {list}\n> - **Options**: {option 1} vs {option 2} [vs ...]\n> - **Lean**: {which option and why}\n> - **Non-goals**: {what's explicitly out of scope}\n> - **Related ADRs\u002Fcode**: {what exists that this interacts with}\n> - **Affected files\u002Fareas**: {where in the codebase this lands}\n> - **Verification**: {how we'll know it's implemented correctly}\n>\n> **Does this capture your intent? Anything to add or correct?**\n\nDo NOT proceed to Phase 2 until the human confirms the summary.\n\n### Phase 2: Draft the ADR\n\n1. **Choose the ADR directory.**\n   - If one exists (found in Phase 0), use it.\n   - If none exists, create `contributing\u002Fdecisions\u002F` (if `contributing\u002F` exists), `docs\u002Fdecisions\u002F` (MADR default), or `adr\u002F` (simpler repos).\n\n2. **Choose a filename strategy.**\n   - If existing ADRs use date prefixes (`YYYY-MM-DD-...`), continue that.\n   - Otherwise use slug-only filenames (`choose-database.md`).\n\n3. **Choose a template.**\n   - Use `assets\u002Ftemplates\u002Fadr-simple.md` for straightforward decisions (one clear winner, minimal tradeoffs).\n   - Use `assets\u002Ftemplates\u002Fadr-madr.md` when you need to document multiple options with structured pros\u002Fcons\u002Fdrivers.\n   - See `references\u002Ftemplate-variants.md` for guidance.\n\n4. **Fill every section from the confirmed intent summary.** Do not leave placeholder text. Every section should contain real content or be removed (optional sections only).\n\n5. **Write the Implementation Plan.** This is the most important section for agent-first ADRs. It tells the next agent exactly what to do. See the template for structure.\n\n6. **Write Verification criteria as checkboxes.** These must be specific enough that an agent can programmatically or manually check each one.\n\n7. **Generate the file.**\n   - Preferred: run `scripts\u002Fnew_adr.js` (handles directory, naming, and optional index updates).\n   - If you can't run scripts, copy a template from `assets\u002Ftemplates\u002F` and fill it manually.\n\n### Phase 3: Review Against Checklist\n\nAfter drafting, review the ADR against the agent-readiness checklist in `references\u002Freview-checklist.md`.\n\n**Present the review as a summary**, not a raw checklist dump. Format:\n\n> **ADR Review**\n>\n> ✅ **Passes**: {list what's solid — e.g., \"context is self-contained, implementation plan covers affected files, verification criteria are checkable\"}\n>\n> ⚠️ **Gaps found**:\n>\n> - {specific gap 1 — e.g., \"Implementation Plan doesn't mention test files — which test suite should cover this?\"}\n> - {specific gap 2}\n>\n> **Recommendation**: {Ship it \u002F Fix the gaps first \u002F Needs more Phase 1 work}\n\nOnly surface failures and notable strengths — do not recite every passing checkbox.\n\nIf there are gaps, propose specific fixes. Do not just flag problems — offer solutions and ask the human to approve.\n\nDo not finalize until the ADR passes the checklist or the human explicitly accepts the gaps.\n\n## Consulting ADRs (Read Workflow)\n\nAgents should read existing ADRs **before implementing changes** in a codebase that has them. This is not part of the create-an-ADR workflow — it's a standalone operation any agent should do.\n\n### When to Consult ADRs\n\n- Before starting work on a feature that touches architecture (auth, data layer, API design, infrastructure)\n- When you encounter a pattern in the code and wonder \"why is it done this way?\"\n- Before proposing a change that might contradict an existing decision\n- When a human says \"check the ADRs\" or \"there's a decision about this\"\n- When you find an ADR reference in a code comment\n\n### How to Consult ADRs\n\n1. **Find the ADR directory.** Check `contributing\u002Fdecisions\u002F`, `docs\u002Fdecisions\u002F`, `adr\u002F`, `docs\u002Fadr\u002F`, `decisions\u002F`. Also check for an index file (`README.md` or `index.md`).\n\n2. **Scan titles and statuses.** Read the index or list filenames. Focus on `accepted` ADRs — these are active decisions.\n\n3. **Read relevant ADRs fully.** Don't just read the title — read context, decision, consequences, non-goals, AND the Implementation Plan. The Implementation Plan tells you what patterns to follow and what files are governed by this decision.\n\n4. **Respect the decisions.** If an accepted ADR says \"use PostgreSQL,\" don't propose switching to MongoDB without creating a new ADR that supersedes it. If you find a conflict between what the code does and what the ADR says, flag it to the human.\n\n5. **Follow the Implementation Plan.** When implementing code in an area governed by an ADR, follow the patterns specified in its Implementation Plan. If the plan says \"all new queries go through the data-access layer in `src\u002Fdb\u002F`,\" do that.\n\n6. **Reference ADRs in your work.** Add ADR references in code comments and PR descriptions (see \"Code ↔ ADR Linking\" below).\n\n## Code ↔ ADR Linking\n\nADRs should be bidirectionally linked to the code they govern.\n\n### ADR → Code (in the Implementation Plan)\n\nThe Implementation Plan section names specific files, directories, and patterns:\n\n```markdown\n## Implementation Plan\n\n- **Affected paths**: `src\u002Fdb\u002F`, `src\u002Fconfig\u002Fdatabase.ts`, `tests\u002Fintegration\u002F`\n- **Pattern**: all database queries go through `src\u002Fdb\u002Fclient.ts`\n```\n\n### Code → ADR (in comments)\n\nWhen implementing code guided by an ADR, add a comment referencing it:\n\n```typescript\n\u002F\u002F ADR: Using better-sqlite3 for test database\n\u002F\u002F See: docs\u002Fdecisions\u002F2025-06-15-use-sqlite-for-test-database.md\nimport Database from 'better-sqlite3';\n```\n\nKeep these lightweight — one comment at the entry point, not on every line. The goal is discoverability: when a future agent reads this code, they can find the reasoning.\n\n### Why This Matters\n\n- An agent working in `src\u002Fdb\u002F` can find which ADRs govern that area\n- An agent reading an ADR can find the code that implements it\n- When an ADR is superseded, the code references make it easy to find all code that needs updating\n\n## Other Operations\n\n### Update an Existing ADR\n\n1. Identify the intent:\n   - **Accept \u002F reject**: change status, add any final context.\n   - **Deprecate**: status → `deprecated`, explain replacement path.\n   - **Supersede**: create a new ADR, link both ways (old → new, new → old).\n   - **Add learnings**: append to `## More Information` with a date stamp. Do not rewrite history.\n\n2. Use `scripts\u002Fset_adr_status.js` for status changes (supports YAML front matter, bullet status, and section status).\n\n### Post-Acceptance Lifecycle\n\nAfter an ADR is accepted:\n\n1. **Create implementation tasks.** Each item in the Implementation Plan and each follow-up in Consequences should become a trackable task (issue, ticket, or TODO).\n2. **Reference the ADR in PRs.** Link to the ADR in PR descriptions, e.g. \"Implements `contributing\u002Fdecisions\u002F2025-06-15-use-sqlite-for-test-database.md`.\"\n3. **Add code references.** Add ADR path comments at key implementation points.\n4. **Check verification criteria.** Once implementation is complete, walk through the Verification checkboxes. Update the ADR with results in `## More Information`.\n5. **Revisit when triggers fire.** If the ADR specified revisit conditions (\"if X happens, reconsider\"), monitor for those conditions.\n\n### Index\n\nIf the repo has an ADR index\u002Flog file (often `README.md` or `index.md` in the ADR dir), keep it updated.\n\nPreferred: let `scripts\u002Fnew_adr.js --update-index` do it. Otherwise:\n\n- Add a bullet entry for the new ADR.\n- Keep ordering consistent (numeric if numbered; date or alpha if slugs).\n\n### Bootstrap\n\nWhen introducing ADRs to a repo that has none:\n\n```bash\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fbootstrap_adr.js\n```\n\nThis creates the directory, an index file, and a filled-out first ADR (\"Adopt architecture decision records\") with real content explaining why the team is using ADRs. Use `--json` for machine-readable output. Use `--dir` to override the directory name.\n\n### Categories (Large Projects)\n\nFor repos with many ADRs, organize by subdirectory:\n\n```\ndocs\u002Fdecisions\u002F\n  backend\u002F\n    2025-06-15-use-postgres.md\n  frontend\u002F\n    2025-06-20-use-react.md\n  infrastructure\u002F\n    2025-07-01-use-terraform.md\n```\n\nDate prefixes are local to each category. Choose a categorization scheme early (by layer, by domain, by team) and document it in the index.\n\n## Resources\n\n### scripts\u002F\n\n- `scripts\u002Fnew_adr.js` — create a new ADR file from a template, using repo conventions.\n- `scripts\u002Fset_adr_status.js` — update an ADR status in-place (YAML front matter or inline). Use `--json` for machine output.\n- `scripts\u002Fbootstrap_adr.js` — create ADR dir, `README.md`, and initial \"Adopt ADRs\" decision.\n\n### references\u002F\n\n- `references\u002Freview-checklist.md` — agent-readiness checklist for Phase 3 review.\n- `references\u002Fadr-conventions.md` — directory, filename, status, and lifecycle conventions.\n- `references\u002Ftemplate-variants.md` — when to use simple vs MADR-style templates.\n- `references\u002Fexamples.md` — filled-out short and long ADR examples with implementation plans.\n\n### assets\u002F\n\n- `assets\u002Ftemplates\u002Fadr-simple.md` — lean template for straightforward decisions.\n- `assets\u002Ftemplates\u002Fadr-madr.md` — MADR 4.0 template for decisions with multiple options and structured tradeoffs.\n- `assets\u002Ftemplates\u002Fadr-readme.md` — default ADR index scaffold used by `scripts\u002Fbootstrap_adr.js`.\n\n### Script Usage\n\nFrom the target repo root:\n\n```bash\n# Simple ADR\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fnew_adr.js --title \"Choose database\" --status proposed\n\n# MADR-style with options\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fnew_adr.js --title \"Choose database\" --template madr --status proposed\n\n# With index update\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fnew_adr.js --title \"Choose database\" --status proposed --update-index\n\n# Bootstrap a new repo\nnode \u002Fpath\u002Fto\u002Fadr-skill\u002Fscripts\u002Fbootstrap_adr.js --dir docs\u002Fdecisions\n```\n\nNotes:\n\n- Scripts auto-detect ADR directory and filename strategy.\n- Use `--dir` and `--strategy` to override.\n- Use `--json` to emit machine-readable output.\n",{"name":5,"metadata":24,"description":7},{"internal":25},true,"master","4aa004da461d820f4ea5499e58eb8d196cf99016","community\u002Fskills_sh\u002Fs\u002Fskills-sh_vercel_ai_adr-skill",0,"https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge","https:\u002F\u002Fskill-explorer-rho.vercel.app","https:\u002F\u002Fgithub.com\u002FLord1Egypt","Unbreakable. Unstoppable. Unmatched⚡.\r\n Speaker of machine tongues 🤖  | World-builder of decentralized dreams 🌐 | Defender of the digital realm🛡️.","2026-06-10 08:21:01",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":25},[37,40,43],{"tool":38,"command":39},"npx","npx skills add Lord1Egypt\u002Fawesome-skill-forge --skill adr-skill",{"tool":41,"command":42},"bunx","bunx skills add Lord1Egypt\u002Fawesome-skill-forge --skill adr-skill",{"tool":44,"command":45},"pnpm","pnpm dlx skills add Lord1Egypt\u002Fawesome-skill-forge --skill adr-skill","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fcommunity\u002Fskills_sh\u002Fs\u002Fskills-sh_vercel_ai_adr-skill\u002FSKILL.md",[],[49,56,63,70,77,84],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M785WKJB99G3STR1NF9NRTJW","youtube-content","YouTube transcripts to summaries, threads, blogs.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fyoutube-content\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M785WEFHB0G2S9YA6EPR3H0E","xurl","X\u002FTwitter via xurl CLI: post, search, DM, media, v2 API.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fxurl\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M785W98EDN4EFJXJPMQEHCRC","touchdesigner-mcp","Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Ftouchdesigner-mcp\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M785W5S9FP3QBH2V191E025P","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M785W2AS08NSSH9YATCV6FJB","teams-meeting-pipeline","Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fteams-meeting-pipeline\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M785VXKW4T34BTP1SCHW1R7F","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fsystematic-debugging\u002FSKILL.md",[],[]]