nguyenthienthanh · nguyenthienthanh · Aug 25, 2026 · Aug 24, 2026 · Aug 25, 2026 · Aug 25, 2026
diff --git a/README.md b/README.md
@@ -233,7 +233,7 @@ Disable any pillar individually via env var: `AF_SELF_HEAL_DISABLED`, `AF_MCP_AU
 
 ## Works Across AI Coding Tools
 
-Aura Frog's 72 rules, 42 skills, and 15 agents are **~87% portable** (weighted average) because they're markdown conventions, not tool-specific code. Only the thin hook layer needs adapters.
+Aura Frog's 72 rules, 43 skills, and 15 agents are **~87% portable** (weighted average) because they're markdown conventions, not tool-specific code. Only the thin hook layer needs adapters.
 
 | Tool | Status | Coverage |
 |------|--------|:--------:|
@@ -311,7 +311,7 @@ Expected output:
 🐸 Aura Frog v3.8.0-alpha.12 — Ready
   Agents:   15 loaded (lead, architect, frontend, mobile, tester, security, devops, strategist, scanner,
                        master-planner, feature-architect, story-planner, replanner, epic-summarizer, conflict-arbiter)
-  Skills:   42 available (9 auto-invoke, 33 on-demand)
+  Skills:   43 available (10 auto-invoke, 33 on-demand)
   Rules:    72 loaded (22 core + 20 agent + 30 workflow)
   Hooks:    51 registered
   MCP:      context7, playwright, vitest, firebase, figma, slack
@@ -441,7 +441,7 @@ Details: `rules/core/execution-rules.md`, `skills/agent-detector/SKILL.md`, `ski
 | Component | Count | Why it matters |
 |-----------|:-----:|----------------|
 | **Agents** | 15 | Right expert auto-selected per task (build + review + planning + safety roles) |
-| **Skills** | 42 | 9 auto-invoke on context, 33 on-demand (incl. `design-vision-loop`) |
+| **Skills** | 43 | 10 auto-invoke on context, 33 on-demand (incl. `design-vision-loop`) |
 | **Commands** | 24 | Core: `/run`, `/check`, `/design`, `/project`, `/af`, `/help` + `/aura-frog:*` hierarchical-planning suite (14 user-facing + 10 legacy `/aura-frog:plan-<verb>` alias stubs) |
 | **Rules** | 72 | 3-tier loading (22 core + 20 agent + 30 workflow) — only what's needed |
 | **Hooks** | 51 | Conditional — skip processing for non-code files (v3.7.2 adds `bare-word-router.cjs`) |
@@ -629,7 +629,7 @@ Honest comparison with two popular plugins in the ecosystem (April 2026).
 | | **Aura Frog** | **wshobson/agents** | **Superpowers** |
 |---|---|---|---|
 | **Agents** | 15 curated | 184 across 78 plugins | ~20 |
-| **Skills** | 42 | 150 | Small focused set |
+| **Skills** | 43 | 150 | Small focused set |
 | **Commands** | 24 (14 user-facing + 10 legacy aliases) | 98 | ~10 |
 | **Workflow** | 5-phase TDD with 2 gates | No structured workflow | Phase-gated workflow |
 | **Agent routing** | Task-content Layer 0 override | Manual `/agent-name` | Similar to Aura Frog |
@@ -685,7 +685,7 @@ Use this checklist:
 - ✅ MCP-heavy workflows (Figma + Firebase + Slack + DBs) → per-agent allowlists + audit log
 - ⚠️ Single-file edits / quick prototypes → workflow overhead may not pay off; use `/run task: …` to bypass
 - ⚠️ Haiku-only budget — some features (planning, conflict, design phases) prefer Sonnet/Opus
-- ⚠️ Minimalist-plugin preference — Aura Frog is substantial (15 agents, 42 skills, 72 rules, 51 hooks)
+- ⚠️ Minimalist-plugin preference — Aura Frog is substantial (15 agents, 43 skills, 72 rules, 51 hooks)
 
 ---
 
@@ -697,7 +697,7 @@ Use this checklist:
 | **Getting Started** | [GET_STARTED.md](docs/getting-started/GET_STARTED.md) |
 | **First Workflow Tutorial** | [FIRST_WORKFLOW_TUTORIAL.md](docs/getting-started/FIRST_WORKFLOW_TUTORIAL.md) |
 | **All Commands (24)** | [commands/README.md](aura-frog/commands/README.md) |
-| **All Skills (42)** | [skills/README.md](aura-frog/skills/README.md) |
+| **All Skills (43)** | [skills/README.md](aura-frog/skills/README.md) |
 | **Agent Teams Guide** | [AGENT_TEAMS_GUIDE.md](docs/guides/AGENT_TEAMS_GUIDE.md) |
 | **MCP Setup** | [MCP_GUIDE.md](docs/operations/MCP_GUIDE.md) |
 | **Hooks & Lifecycle** | [hooks/README.md](aura-frog/hooks/README.md) |
@@ -715,7 +715,7 @@ TOON = Compression       Approval Gates = Interrupts    Handoffs = IPC
 
 aura-frog/
 ├── agents/         15 processes (auto-dispatched per task)
-├── skills/         42 skills (9 auto-invoke + 33 on-demand)
+├── skills/         43 skills (10 auto-invoke + 33 on-demand)
 ├── commands/       24 commands (core /run /check /design /project /af /help + /aura-frog:* hierarchical-planning suite)
 ├── rules/          72 rules (22 core + 20 agent + 30 workflow)
 ├── hooks/          50 lifecycle hooks (conditional execution)

diff --git a/aura-frog/.claude-plugin/plugin.json b/aura-frog/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "aura-frog",
   "version": "3.8.0-alpha.12",
-  "description": "Planning-first LLM OS for software engineering. Hierarchical planning (T0-T4) survives session reset · forensic reasoning traces · L1+L2 conflict detection · self-healing safety gates · per-agent MCP security · durable project-context snapshots · cross-tool porter (Copilot/Codex/Cursor) · CLI dashboard. 15 agents, 5-phase TDD, 72 rules (3-tier), 42 skills, 24 commands, 51 hooks, 6 MCP servers. ~87% markdown. Backward-compatible with /run.",
+  "description": "Planning-first LLM OS for software engineering. Hierarchical planning (T0-T4) survives session reset · forensic reasoning traces · L1+L2 conflict detection · self-healing safety gates · per-agent MCP security · durable project-context snapshots · cross-tool porter (Copilot/Codex/Cursor) · CLI dashboard. 15 agents, 5-phase TDD, 72 rules (3-tier), 43 skills, 24 commands, 51 hooks, 6 MCP servers. ~87% markdown. Backward-compatible with /run.",
   "author": {
     "name": "Nguyen Thien Thanh",
     "email": "nguyenthienthanh.kiyoshi@gmail.com",

diff --git a/aura-frog/CLAUDE.md b/aura-frog/CLAUDE.md
@@ -279,7 +279,7 @@ resources[8]{name,location}:
   Agents (15),agents/
   Commands (24),commands/
   Rules (72),rules/{core|agent|workflow}/
-  Skills (42),skills/
+  Skills (43),skills/
   Hooks (51),hooks/
   MCP (6),.mcp.json (all enabled; postgres/redis/chrome-devtools/codebase-memory/stitch unbundled — see docs/operations/MCP_GUIDE.md)
   AI References,docs/

diff --git a/aura-frog/README.md b/aura-frog/README.md
@@ -592,7 +592,7 @@ This overrides every agent/skill `model:` declaration. See [Per-Agent Model Over
 /run worktree: <task>    # Automatically creates isolated worktree + runs there
 ```
 
-Each worktree has its own state in `.claude/logs/runs/<id>/`. See [Git Worktree skill](aura-frog/skills/git-worktree/SKILL.md).
+Each worktree has its own state in `.claude/logs/runs/<id>/`. See the [git skill](aura-frog/skills/git/SKILL.md).
 
 For full multi-agent parallel work, enable Agent Teams:
 ```bash

diff --git a/aura-frog/rules/workflow/workflow-deliverables.md b/aura-frog/rules/workflow/workflow-deliverables.md
@@ -26,10 +26,12 @@ Syntax: `files[3]{path,action,purpose}:` for tabular data. See [TOON format](htt
 ## Phase Deliverables
 
 ```toon
-deliverables[12]{phase,document,required,key_content}:
+deliverables[14]{phase,document,required,key_content}:
   1,REQUIREMENTS.md,YES,User stories + acceptance criteria + scope
   1,TECH_SPEC.md,YES,AI-readable: architecture + files + APIs + risks
   1,TECH_SPEC_CONFLUENCE.md,YES,Human-readable: full Confluence format
+  1,DESIGN_DECISIONS.md,YES,Decision records — tiered Y-statement/ADR/MADR/RFC
+  1,LLD.md,If design-heavy,Low-level design — data/API/errors/ops
   1,UI_BREAKDOWN.md,If UI,Components + props + accessibility
   2,TEST_PLAN.md,YES,Test scenarios + coverage targets
   2,Test files,YES,Failing tests (TDD RED)
@@ -52,6 +54,8 @@ deliverables[12]{phase,document,required,key_content}:
 ├── REQUIREMENTS.md
 ├── TECH_SPEC.md              # AI reads this
 ├── TECH_SPEC_CONFLUENCE.md   # Human-readable
+├── DESIGN_DECISIONS.md       # Decision records (tiered)
+├── LLD.md                    # Low-level design (if design-heavy)
 ├── UI_BREAKDOWN.md           # If UI
 ├── TEST_PLAN.md
 ├── CODE_REVIEW.md

diff --git a/aura-frog/scripts/workflow/scaffold-phase-deliverables.sh b/aura-frog/scripts/workflow/scaffold-phase-deliverables.sh
@@ -106,7 +106,8 @@ scaffold_phase() {
       scaffold_one 1 "REQUIREMENTS.md"          "requirements.md"
       scaffold_one 1 "TECH_SPEC.md"             "tech-spec-toon.md"
       scaffold_one 1 "TECH_SPEC_CONFLUENCE.md"  "confluence-page.md"
-      scaffold_one 1 "DESIGN_DECISIONS.md"      "lld.md"
+      scaffold_one 1 "DESIGN_DECISIONS.md"      "decision-record.md"
+      scaffold_one 1 "LLD.md"                   "lld.md"
       ;;
     2)
       scaffold_one 2 "TEST_PLAN.md"             "test-plan-toon.md"

diff --git a/aura-frog/skills/documentation/SKILL.md b/aura-frog/skills/documentation/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: documentation
-description: "Create Architecture Decision Records (ADRs) and Runbooks for operational documentation."
+description: "Create Runbooks for operational documentation. For ADRs, tech specs, requirements, LLD and technical analysis use the tech-writing skill instead."
 autoInvoke: false
 priority: medium
 triggers:
@@ -19,8 +19,10 @@ user-invocable: false
 
 ## When to Create
 
-- **ADR:** Technology choices, architectural changes, new patterns, deprecations
 - **Runbook:** Service deployment, common ops tasks, incident response
+- **ADR:** → use `skills/tech-writing` + `templates/decision-record.md`. That template carries the
+  full 4-tier ladder (Y-statement → Nygard ADR → MADR → RFC) and picks the tier by decision size.
+  The stripped ADR template below is kept only so existing links keep resolving.
 
 ## ADR Template