akili-specs 2.6.0 → 2.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Archive a completed spec task, run the Kaizen retrospective, sync agent guides and CodeGraph, and keep the TRD current.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Archive AKILI-SPECS Spec
@@ -92,6 +95,8 @@ If readiness is unclear, stop and ask the user whether to proceed, validate firs
92
95
 
93
96
  ### Step 2: Create Archive Summary
94
97
 
98
+ Write the summary (and later the Kaizen log entry) following `cognitive-doc-design`: lead with the outcome, keep sections small, and prefer tables and checklists over prose.
99
+
95
100
  Before moving the folder, create or update:
96
101
 
97
102
  ```text
@@ -172,3 +177,9 @@ Present:
172
177
  - Do not delete spec folders as part of archiving; only move them into `docs/specs/archive/`.
173
178
  - The Kaizen retrospective must never block the archive. If retrospective inputs are missing or the user declines, append a metrics-only (or clean-run) entry to `docs/specs/kaizen-log.md` and continue to Step 5.
174
179
  - Never edit files outside `docs/specs/kaizen-log.md` without explicit user approval in Step 4.3.
180
+
181
+ ---
182
+
183
+ ## Authorship
184
+
185
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Run spec-to-code drift auditing to detect differences between active codebase reality and the active UX/UI design and TRD.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Audit AKILI Specifications for Drift
@@ -95,3 +98,9 @@ Summarize the conformance score, key discrepancies found, and recommended remedi
95
98
  1. Fix documented specs (update baseline docs in place).
96
99
  2. Schedule task specs to implement missing functionality in the code.
97
100
  3. Keep the report for review.
101
+
102
+ ---
103
+
104
+ ## Authorship
105
+
106
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Establish or strengthen the project-wide AKILI-SPECS foundation and baseline docs (PRD, UX/UI Design, TRD).
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Establish AKILI-SPECS Constitution
@@ -119,6 +122,8 @@ Focus especially on:
119
122
  - Infrastructure expectations (e.g., AWS, deployment platforms, architectural rules, specific cloud components required)
120
123
  - Preferred `docs/specs/` taxonomy when the repo does not already imply one
121
124
 
125
+ Use the `product-manager-toolkit` skill's **Customer Interview Guide** and **Hypothesis Template** as the question script. If the user has interview transcripts or raw customer feedback available, offer its `customer_interview_analyzer.py` helper to extract pain points, jobs-to-be-done, and themes before drafting.
126
+
122
127
  Ask only what is needed to avoid unstable assumptions.
123
128
 
124
129
  ---
@@ -127,7 +132,7 @@ Ask only what is needed to avoid unstable assumptions.
127
132
 
128
133
  Create or enhance `docs/prd.md` as a concise living document.
129
134
 
130
- **Primary skill:** `product-manager-toolkit`
135
+ **Primary skill:** `product-manager-toolkit` — follow its **AKILI-SPECS Integration** section: the Required PRD structure below is canonical (never substitute the toolkit's own PRD templates); use its North Star Metric framework for "Goals & Success Metrics", jobs-to-be-done for "Target Personas", and its Hypothesis Template for "Assumptions". Write the document following `cognitive-doc-design`: lead with the answer, progressive disclosure, tables and checklists over prose.
131
136
 
132
137
  **PRD rules:**
133
138
 
@@ -416,3 +421,9 @@ Ask the user whether to approve or request changes. If changes are requested, re
416
421
  ## Outcome
417
422
 
418
423
  At the end of `/akili-constitution`, the repository should have a project-level baseline that future `/akili-specify`, `/akili-execute`, `/akili-validate`, and `/akili-test` work can rely on without guessing the structure or conventions. The `.agents/` personas must be in place so that `/akili-execute` can run the Leader → Implementer → Reviewer rework loop and `/akili-test` can run the Leader → Tester(s) harness without falling back to inline personas. The root guides must also carry a `## Model Routing` registry (Step 8C) so each phase runs on a model matched to its demand, with the Reviewer on a different model than the Implementer.
424
+
425
+ ---
426
+
427
+ ## Authorship
428
+
429
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Execute approved specs systematically following the AKILI-SPECS methodology with spec-to-code traceability.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Execute AKILI-SPECS Tasks
@@ -173,7 +176,7 @@ Only after a Reviewer `PASS`:
173
176
 
174
177
  1. Update `tasks.md` from `[ ]` (or `[~]`) to `[x]`.
175
178
  2. Append a structured entry to `execution.md` (see log format below) covering every attempt in this task's loop.
176
- 3. **Git Commit Staging:** Always follow the **AKILI Spec Reference** commit standard. Prefix the commit message with `[SPEC:<spec-path>]` (e.g. `git commit -m "[SPEC:changes/add-remember-me] implement secure cookie storage"`).
179
+ 3. **Git Commit Staging:** Always follow the **AKILI Spec Reference** commit standard. Prefix the commit message with `[SPEC:<spec-path>]` (e.g. `git commit -m "[SPEC:changes/add-remember-me] implement secure cookie storage"`). When writing a PR description for the spec's work, load `cognitive-doc-design` and follow its PR and Review Docs rules: state what to review first, what is intentionally out of scope, and link chained PRs.
177
180
  4. **Code Traceability:** Add file-level or block-level comment spec references (`// @akili-spec <spec-path>`) in critical or complex codebase additions to assist future audits.
178
181
  5. **Constitution Impact Check:** If the task created a new module/package, moved a module boundary, or changed a module's public surface, append a `## Constitution Impact: <Task ID>` block to `execution.md` recording:
179
182
  - which module was created or reshaped
@@ -240,3 +243,9 @@ A minimal PASS-on-first-attempt entry can be compact; a HALT or rework entry mus
240
243
  2. Document the blocker, alternatives, and revised technical direction in `execution.md` inside a new `## Pivot Record: <Task ID>` section.
241
244
  3. Modify the spec's `requirements.md`, `design.md`, and/or `tasks.md` to map out the updated plan.
242
245
  4. Stop, explain the situation to the user, and obtain explicit review/approval on the pivot before resuming execution.
246
+
247
+ ---
248
+
249
+ ## Authorship
250
+
251
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Propose new features or changes by initiating a new detailed technical spec process.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Propose AKILI-SPECS Change
@@ -121,6 +124,7 @@ Use `brainstorming` and, when helpful, `product-manager-toolkit` to clarify:
121
124
 
122
125
  **Scope Chunking:** If the user provides a very large or multi-faceted instruction (e.g., an entire epic or multiple distinct features), analyze whether the request should be split into multiple bounded proposals.
123
126
  - If it should be split, propose breaking it down to the user.
127
+ - When recommending the build order of the resulting chunks, score them with RICE or MoSCoW from the `product-manager-toolkit` skill (AKILI-SPECS Integration section) instead of guessing.
124
128
  - Upon agreement, create the respective folders for each bounded change under `docs/specs/` and generate a `proposal.md` for each.
125
129
 
126
130
  Ask focused questions only when the proposal would otherwise depend on unstable assumptions.
@@ -250,3 +254,9 @@ Generate a short, easy-to-understand summary (summary facil de entender de lo qu
250
254
  7. next command to run after approval (matched to the type)
251
255
 
252
256
  Ask whether to approve the proposal, revise it, or stop.
257
+
258
+ ---
259
+
260
+ ## Authorship
261
+
262
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Fast-track a trivial, low-risk change (copy edit, color tweak, small style/text change) with minimal traceability and automatic escalation when it is not actually trivial.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Fast-Track a Trivial AKILI-SPECS Change
@@ -123,3 +126,9 @@ Generate a short, easy-to-understand summary (summary facil de entender de lo qu
123
126
  - One change per invocation. Batch unrelated tweaks into separate `/akili-quick` runs or a proper spec.
124
127
  - When in doubt about triviality, escalate. A wrongly fast-tracked change costs more than a Lite spec.
125
128
  - Keep the edit and the context minimal — this command's whole value is speed and low token cost.
129
+
130
+ ---
131
+
132
+ ## Authorship
133
+
134
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Resume work after a session break by scanning active specs and presenting a multi-spec dashboard briefing.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Resume AKILI-SPECS Session
@@ -124,3 +127,9 @@ No files are created or modified. The command outputs a screen summary only.
124
127
  - If `docs/specs/` does not exist, report that the project has no active specs and suggest running `/akili-constitution` or `/akili-propose`.
125
128
  - If `docs/specs/` is empty (only `archive/` exists), report that all specs are archived and suggest running `/akili-propose` for new work.
126
129
  - If a spec folder exists but has no readable files, report it as an incomplete spec and suggest running `/akili-specify <spec-path>`.
130
+
131
+ ---
132
+
133
+ ## Authorship
134
+
135
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Enhance pages and search engine optimization following SEO best practices.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # SEO Setup & Audit via Google Search Console
@@ -275,3 +278,9 @@ After the command completes, verify:
275
278
  - If `search_analytics_query` returns no rows for a newly verified property, this is expected. Do not mark as failure.
276
279
  - If the Indexing API is suggested as a fix, decline it for non-`JobPosting`/`BroadcastEvent` content and explain why.
277
280
  - If a skill is unavailable, fall back to the next documented skill and note it in the report.
281
+
282
+ ---
283
+
284
+ ## Authorship
285
+
286
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Draft detailed requirements, UI/UX designs, and technical tasks for a proposed feature.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Generate AKILI-SPECS for Module
@@ -95,11 +98,12 @@ Use `brainstorming` and, when helpful, `product-manager-toolkit` to clarify:
95
98
 
96
99
  **Scope Chunking:** If the user provides a very large instruction or epic, evaluate if it is too massive for a single spec.
97
100
  - If it spans multiple distinct modules or features, propose splitting the spec into multiple separate specs.
101
+ - When recommending the build order of the split specs, score them with RICE or MoSCoW from the `product-manager-toolkit` skill (AKILI-SPECS Integration section) instead of guessing.
98
102
  - If the user agrees, create the separate folders under `docs/specs/` and draft a `proposal.md` or jump straight to the split documents (`requirements.md`, `design.md`, `tasks.md`) for each chunk.
99
103
 
100
104
  #### Step 1.2 — Write
101
105
 
102
- Generate `requirements.md` using `docs/specs/general-setup/requirements.md` as the format source.
106
+ Generate `requirements.md` using `docs/specs/general-setup/requirements.md` as the format source. Write every spec document (`requirements.md`, `design.md`, `tasks.md`) following `cognitive-doc-design`: lead with the answer, progressive disclosure, and tables/checklists/scenarios over prose.
103
107
 
104
108
  Minimum content:
105
109
 
@@ -288,7 +292,7 @@ Preferred UI/UX skill rule:
288
292
  Present a clear summary of the generated tasks on the screen, including:
289
293
  - A high-level list of the tasks to be implemented so the user understands the plan without reading the full document.
290
294
  - An **Estimated Lines of Code (LOC)** output for the entire spec.
291
- - A **PR Strategy Recommendation**: If the estimate exceeds ~400 LOC or the task graph is highly complex, recommend splitting the implementation into multiple Pull Requests and suggest logical boundaries (e.g., "PR 1: Backend/API, PR 2: Frontend UI").
295
+ - A **PR Strategy Recommendation**: If the estimate exceeds ~400 LOC or the task graph is highly complex, recommend splitting the implementation into multiple Pull Requests and suggest logical boundaries (e.g., "PR 1: Backend/API, PR 2: Frontend UI"). When PRs are chained, note that their descriptions should follow `cognitive-doc-design` review-empathy rules (what to review first, what is out of scope, link previous/next PR).
292
296
 
293
297
  Then explicitly ask the user how to proceed, providing these options:
294
298
 
@@ -333,3 +337,9 @@ When the spec is ready, generate a short, easy-to-understand summary (summary fa
333
337
  7. Open questions or assumptions that still need user confirmation
334
338
 
335
339
  If a proposal existed, mention whether the generated spec stayed aligned with it or changed based on implementation discovery.
340
+
341
+ ---
342
+
343
+ ## Authorship
344
+
345
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Write and execute comprehensive automated unit/integration tests for the implemented feature.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Test AKILI-SPECS Implementation
@@ -174,3 +177,9 @@ If `ui-ux-pro-max` is unavailable, use `frontend-design` plus the UX/UI design d
174
177
  - If no automated test is practical, document the manual verification steps and why automation was deferred.
175
178
  - A Tester must never rewrite a test to hide a genuine product defect; a real failure is reported as `PRODUCT_BUG`, not silenced.
176
179
  - Do not delegate trivial single-test work to a subagent when running it inline is cheaper (see the Deployment Rule).
180
+
181
+ ---
182
+
183
+ ## Authorship
184
+
185
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -1,5 +1,8 @@
1
1
  ---
2
2
  description: Validate that the implemented feature strictly matches all requirements, design tokens, and user flows.
3
+ license: MIT
4
+ metadata:
5
+ author: Juan Carlos Cadavid (jcadavid.com)
3
6
  ---
4
7
 
5
8
  # Validate AKILI-SPECS Implementation
@@ -184,3 +187,9 @@ The work is ready to consider complete when:
184
187
  - tests cover the key requirements and scenarios
185
188
  - implementation drift is reflected in the AKILI-SPECS docs or execution notes
186
189
  - the user has reviewed the validation summary
190
+
191
+ ---
192
+
193
+ ## Authorship
194
+
195
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -0,0 +1,81 @@
1
+ ---
2
+ name: cognitive-doc-design
3
+ description: "Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs."
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: gentleman-programming
7
+ version: "1.0"
8
+ ---
9
+
10
+ ## When to Use
11
+
12
+ Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review.
13
+
14
+ Use it especially for:
15
+
16
+ - PR descriptions and review notes.
17
+ - Contributor or maintainer guides.
18
+ - Architecture, workflow, or onboarding docs.
19
+ - Any doc that currently feels long, dense, or hard to scan.
20
+
21
+ ## Critical Patterns
22
+
23
+ | Pattern | Rule |
24
+ |---------|------|
25
+ | Lead with the answer | Put the decision, action, or outcome first. Context comes after. |
26
+ | Progressive disclosure | Start with the happy path, then add details, edge cases, and references. |
27
+ | Chunking | Group related information into small sections. Keep flat lists short. |
28
+ | Signposting | Use headings, labels, callouts, and summaries so readers know where they are. |
29
+ | Recognition over recall | Prefer tables, checklists, examples, and templates over prose that must be remembered. |
30
+ | Review empathy | Design docs so reviewers can verify intent without reconstructing the whole story. |
31
+
32
+ ## Documentation Shape
33
+
34
+ Use this default structure unless the repo already provides a stronger template:
35
+
36
+ ```markdown
37
+ # <Outcome-oriented title>
38
+
39
+ <One paragraph: what changed, who it helps, and why it matters.>
40
+
41
+ ## Quick path
42
+
43
+ 1. <First action>
44
+ 2. <Second action>
45
+ 3. <Verification or expected result>
46
+
47
+ ## Details
48
+
49
+ | Topic | Decision |
50
+ |-------|----------|
51
+ | <area> | <concise explanation> |
52
+
53
+ ## Checklist
54
+
55
+ - [ ] <Reader can confirm this>
56
+ - [ ] <Reader can confirm that>
57
+
58
+ ## Next step
59
+
60
+ <Link or action that continues the workflow.>
61
+ ```
62
+
63
+ ## PR and Review Docs
64
+
65
+ When documenting a PR, reduce reviewer burnout by making the review path explicit:
66
+
67
+ - State what to review first.
68
+ - State what is intentionally out of scope.
69
+ - Link the previous and next PR when work is chained.
70
+ - Keep each section focused on one decision or unit of work.
71
+ - Use checklists for acceptance criteria and verification.
72
+
73
+ ## Commands
74
+
75
+ ```bash
76
+ # Check markdown files changed in the current branch
77
+ git diff --name-only -- '*.md'
78
+
79
+ # Inspect PR changed-line count for cognitive load
80
+ gh pr view <PR_NUMBER> --json additions,deletions,changedFiles
81
+ ```
@@ -1,12 +1,31 @@
1
1
  ---
2
2
  name: product-manager-toolkit
3
- description: Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development.
3
+ description: Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development. In AKILI-SPECS projects, follow the AKILI-SPECS Integration section first.
4
+ metadata:
5
+ adapted-for: "AKILI-SPECS methodology by Juan Carlos Cadavid — jcadavid.com"
4
6
  ---
5
7
 
6
8
  # Product Manager Toolkit
7
9
 
8
10
  Essential tools and frameworks for modern product management, from discovery to delivery.
9
11
 
12
+ ## AKILI-SPECS Integration
13
+
14
+ When this skill is loaded inside the AKILI-SPECS methodology, this section takes precedence over the generic workflows below. Each tool has one precise moment in the flow:
15
+
16
+ | AKILI moment | Use from this toolkit |
17
+ |---|---|
18
+ | `/akili-constitution` Step 2 (Clarify Missing Business Context) | The **Customer Interview Guide** and **Hypothesis Template** as the question script. If the user has interview transcripts or raw customer feedback, offer `scripts/customer_interview_analyzer.py` to extract pain points, jobs-to-be-done, and themes — they feed the PRD's Problem Statement and Target Personas. |
19
+ | `/akili-constitution` Step 3 (PRD) | **The AKILI 9-section PRD structure is canonical** — never substitute this toolkit's PRD templates for it. Use the toolkit to fill those sections well: **North Star Metric** framework for "Goals & Success Metrics", **jobs-to-be-done** for "Target Personas", the **Hypothesis Template** for "Assumptions, Dependencies, & Constraints". |
20
+ | `/akili-propose` / `/akili-specify` Scope Chunking | When an epic splits into multiple specs, score the chunks with **RICE** (or **MoSCoW** for a quick pass) to recommend the build order. Treat each candidate spec as a row: `name,reach,impact,confidence,effort` → `scripts/rice_prioritizer.py`. |
21
+ | `/akili-propose` (Change track) | The **Feature Brief** mindset maps to `proposal.md`: problem → hypothesis → success criteria. Do not create a separate brief document. |
22
+
23
+ Rules inside AKILI-SPECS:
24
+
25
+ - The scripts are optional helpers (they need Python); never block a flow on them — the frameworks work as reasoning guides on their own.
26
+ - Skip the Go-to-Market and Stakeholder Management sections during constitution work; they are out of scope for `docs/prd.md`.
27
+ - Output always lands in AKILI artifacts (`docs/prd.md`, `proposal.md`, spec folders) — never in standalone PM documents.
28
+
10
29
  ## Quick Start
11
30
 
12
31
  ### For Feature Prioritization
@@ -1,5 +1,7 @@
1
1
  # Product Requirements Document (PRD) Templates
2
2
 
3
+ > **AKILI-SPECS note:** In AKILI-SPECS projects, `docs/prd.md` MUST follow the 9-section structure defined in `/akili-constitution` Step 3 (Overview & Purpose → Problem Statement → Target Personas → Goals & Success Metrics → Scope In/Out → User Stories → Acceptance Criteria → Assumptions/Dependencies/Constraints → Open Questions). The templates below are reference material for filling those sections well — or for PM work outside the methodology — never a replacement structure.
4
+
3
5
  ## Standard PRD Template
4
6
 
5
7
  ### 1. Executive Summary
@@ -34,3 +34,9 @@ When you finish implementing and verifying your task, provide a concise response
34
34
  1. **Task Completed:** (Brief 1-sentence summary of what you implemented)
35
35
  2. **Verification Command Run:** (e.g. `npm run test` or `vitest run`)
36
36
  3. **Verification Output/Evidence:** (Paste passing test outputs or compile success logs)
37
+
38
+ ---
39
+
40
+ ## Authorship
41
+
42
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -75,3 +75,9 @@ After each task completes (whether on first pass or after self-correction), repo
75
75
  6. **Next step:** the next eligible task and a prompt to continue, pause, or skip.
76
76
 
77
77
  Keep this report concise. The full audit trail belongs in `execution.md`, not in chat.
78
+
79
+ ---
80
+
81
+ ## Authorship
82
+
83
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -51,3 +51,9 @@ Use this ONLY if you detect a critical architectural violation, the introduction
51
51
  STATUS: FATAL_FAIL
52
52
  SUMMARY: (Clear explanation of the catastrophic failure and why the loop must be aborted)
53
53
  ```
54
+
55
+ ---
56
+
57
+ ## Authorship
58
+
59
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
@@ -72,3 +72,9 @@ BUG:
72
72
  - **Failing Test:** (test file::test name — kept red on purpose)
73
73
  - **Observed vs Expected:** (actual behavior vs the required behavior)
74
74
  ```
75
+
76
+ ---
77
+
78
+ ## Authorship
79
+
80
+ AKILI-SPECS methodology by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com). Licensed under the MIT License.
package/CHANGELOG.md CHANGED
@@ -10,6 +10,22 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
10
10
 
11
11
  - No unreleased changes yet.
12
12
 
13
+ ## [2.7.1] - 2026-07-20
14
+
15
+ ### Added
16
+
17
+ - **Authorship section in commands and templates:** Every command in `.claude/commands/` and every agent role template in `.claude/templates/` now ends with an `## Authorship` section crediting the AKILI-SPECS methodology to Juan Carlos Cadavid ([jcadavid.com](https://jcadavid.com)).
18
+ - **Authorship in README, LICENSE, and package metadata:** The README gains an `## Authorship` section, the MIT LICENSE copyright line uses the full author name and site, and `package.json` declares the `author` field.
19
+ - **License metadata in commands:** Every command in `.claude/commands/` declares `license: MIT` and `metadata.author` in its frontmatter (matching the convention used by community skills), and the `## Authorship` footer of commands and templates states the MIT License. Third-party skills bundled in `.claude/skills/` keep their original authors and licenses untouched.
20
+ - **Community governance files:** `CONTRIBUTING.md` (PR-only workflow, changelog discipline, and security rules for editing agent-executed prompt files), `SECURITY.md` (private vulnerability reporting with prompt-injection and installer threat scope), and `.github/CODEOWNERS` (maintainer review required on every change).
21
+ ## [2.7.0] - 2026-07-20
22
+
23
+ ### Added
24
+ - **New packaged `cognitive-doc-design` skill** (by gentleman-programming, Apache-2.0): six patterns for docs that reduce cognitive load (lead with the answer, progressive disclosure, chunking, signposting, recognition over recall, review empathy). Wired into the methodology: `/akili-constitution` (PRD writing), `/akili-specify` (all spec documents + chained-PR descriptions), `/akili-execute` (PR and review docs), and `/akili-archive` (archive summary and Kaizen log entries).
25
+
26
+ ### Changed
27
+ - **`product-manager-toolkit` adapted to AKILI-SPECS:** new **AKILI-SPECS Integration** section maps each tool to its exact moment in the flow — Customer Interview Guide + Hypothesis Template as the question script for `/akili-constitution` Step 2 (with the interview analyzer offered when transcripts exist), North Star Metric / jobs-to-be-done / Hypothesis Template to fill the canonical 9-section PRD in Step 3, and RICE/MoSCoW to order scope chunks when `/akili-propose` or `/akili-specify` split an epic into multiple specs. The PRD templates reference now marks the AKILI structure as canonical, and Go-to-Market content is explicitly out of scope for constitution work.
28
+ - **Clear end-of-run summaries in every CLI command:** `akili install` now closes with an **Install Summary** block (per-tool `installed | overwritten | skipped | legacy cleaned` counts with target paths, totals when installing for multiple tools, an explicit dry-run banner, and contextual next steps — `--force` hint, OpenCode restart, `akili doctor` verification). `akili doctor` closes with a **Doctor Summary** (per-tool `HEALTHY | REPAIRED | INCOMPLETE` status with `ok | missing | fixed` counts and repair suggestions). `akili update` closes with an **Update Summary** (version before → after, install type, and how to verify). `akili list` prints a totals line (commands | skills | resources + package version). Overwrites are now counted separately from fresh installs.
13
29
  ## [2.6.0] - 2026-07-20
14
30
 
15
31
  ### Added
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 Juan Cadavid
3
+ Copyright (c) 2026 Juan Carlos Cadavid (jcadavid.com)
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -79,6 +79,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
79
79
  - `api-design-principles`
80
80
  - `aws-serverless`
81
81
  - `brainstorming`
82
+ - `cognitive-doc-design`
82
83
  - `error-handling-patterns`
83
84
  - `frontend-design`
84
85
  - `gsap-core`
@@ -90,6 +91,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
90
91
  - `gsap-timeline`
91
92
  - `gsap-utils`
92
93
  - `judgment-day`
94
+ - `kaizen`
93
95
  - `nestjs-expert`
94
96
  - `product-manager-toolkit`
95
97
  - `react-doctor`
@@ -830,3 +832,9 @@ and the default registry for Claude Code (PRO) and OpenCode Go.
830
832
  - Skills were copied with their bundled references and helper assets.
831
833
  - This repository stores the current methodology baseline so it can be reused or versioned independently.
832
834
  - Dotfiles are snapshots of the working environment and may include plugin source copies for portability.
835
+
836
+ ## Authorship
837
+
838
+ The AKILI-SPECS methodology is created and maintained by **Juan Carlos Cadavid** — [jcadavid.com](https://jcadavid.com).
839
+
840
+ Every command in `.claude/commands/` and every agent role template in `.claude/templates/` carries this authorship notice. The project is released under the [MIT License](LICENSE): you are free to use, modify, and redistribute it, provided the copyright and attribution notices are kept intact.
package/bin/akili.js CHANGED
@@ -227,19 +227,23 @@ function shouldInclude(type, args) {
227
227
  function copySingleFile(sourcePath, targetPath, args) {
228
228
  ensureDirectory(path.dirname(targetPath), args.dryRun);
229
229
 
230
- if (fs.existsSync(targetPath) && !args.force) {
230
+ const exists = fs.existsSync(targetPath);
231
+
232
+ if (exists && !args.force) {
231
233
  console.log(` ${colors.yellow}skip existing${colors.reset} ${targetPath}`);
232
- return { installed: 0, skipped: 1 };
234
+ return { installed: 0, overwritten: 0, skipped: 1 };
233
235
  }
234
236
 
235
- const action = fs.existsSync(targetPath) ? "overwrite" : "install";
237
+ const action = exists ? "overwrite" : "install";
236
238
  console.log(` ${colors.green}${args.dryRun ? "would " : ""}${action}${colors.reset} ${targetPath}`);
237
239
 
238
240
  if (!args.dryRun) {
239
241
  fs.copyFileSync(sourcePath, targetPath);
240
242
  }
241
243
 
242
- return { installed: 1, skipped: 0 };
244
+ return exists
245
+ ? { installed: 0, overwritten: 1, skipped: 0 }
246
+ : { installed: 1, overwritten: 0, skipped: 0 };
243
247
  }
244
248
 
245
249
  function copyDirectoryContents(sourceDir, targetDir, args) {
@@ -247,19 +251,21 @@ function copyDirectoryContents(sourceDir, targetDir, args) {
247
251
 
248
252
  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
249
253
  let installed = 0;
254
+ let overwritten = 0;
250
255
  let skipped = 0;
251
256
 
252
257
  for (const entry of entries) {
253
258
  const sourcePath = path.join(sourceDir, entry.name);
254
259
  const targetPath = path.join(targetDir, entry.name);
260
+ const exists = fs.existsSync(targetPath);
255
261
 
256
- if (fs.existsSync(targetPath) && !args.force) {
262
+ if (exists && !args.force) {
257
263
  console.log(` ${colors.yellow}skip existing${colors.reset} ${targetPath}`);
258
264
  skipped += 1;
259
265
  continue;
260
266
  }
261
267
 
262
- const action = fs.existsSync(targetPath) ? "overwrite" : "install";
268
+ const action = exists ? "overwrite" : "install";
263
269
  console.log(` ${colors.green}${args.dryRun ? "would " : ""}${action}${colors.reset} ${targetPath}`);
264
270
 
265
271
  if (!args.dryRun) {
@@ -269,10 +275,11 @@ function copyDirectoryContents(sourceDir, targetDir, args) {
269
275
  errorOnExist: false,
270
276
  });
271
277
  }
272
- installed += 1;
278
+ if (exists) overwritten += 1;
279
+ else installed += 1;
273
280
  }
274
281
 
275
- return { installed, skipped };
282
+ return { installed, overwritten, skipped };
276
283
  }
277
284
 
278
285
  function getToolRegistryInfo(tool, args) {
@@ -328,6 +335,7 @@ function installTool(tool, args) {
328
335
  const { rootPath, paths } = getToolRegistryInfo(tool, args);
329
336
 
330
337
  let installed = 0;
338
+ let overwritten = 0;
331
339
  let skipped = 0;
332
340
 
333
341
  console.log(`\n${colors.cyan}${tool.toUpperCase()} target: ${rootPath}${colors.reset}`);
@@ -337,51 +345,47 @@ function installTool(tool, args) {
337
345
  console.log(` ${colors.green}Legacy cleanup complete.${colors.reset}`);
338
346
  }
339
347
 
348
+ const add = (result) => {
349
+ installed += result.installed;
350
+ overwritten += result.overwritten;
351
+ skipped += result.skipped;
352
+ };
353
+
340
354
  if (shouldInclude("commands", args)) {
341
355
  for (const targetCommands of paths.commands) {
342
- const result = copyDirectoryContents(SOURCE_COMMANDS, targetCommands, args);
343
- installed += result.installed;
344
- skipped += result.skipped;
356
+ add(copyDirectoryContents(SOURCE_COMMANDS, targetCommands, args));
345
357
  }
346
358
  }
347
359
 
348
360
  if (shouldInclude("skills", args)) {
349
- const result = copyDirectoryContents(SOURCE_SKILLS, paths.skills, args);
350
- installed += result.installed;
351
- skipped += result.skipped;
361
+ add(copyDirectoryContents(SOURCE_SKILLS, paths.skills, args));
352
362
  }
353
363
 
354
364
  if (shouldInclude("resources", args)) {
355
365
  for (const scriptName of RESOURCE_SCRIPTS) {
356
- const result = copySingleFile(
357
- path.join(SOURCE_SCRIPTS, scriptName),
358
- path.join(paths.resources, "scripts", scriptName),
359
- args
366
+ add(
367
+ copySingleFile(
368
+ path.join(SOURCE_SCRIPTS, scriptName),
369
+ path.join(paths.resources, "scripts", scriptName),
370
+ args
371
+ )
360
372
  );
361
- installed += result.installed;
362
- skipped += result.skipped;
363
373
  }
364
374
 
365
375
  for (const templateName of AGENT_TEMPLATES) {
366
- const result = copySingleFile(
367
- path.join(SOURCE_TEMPLATES, templateName),
368
- path.join(paths.resources, "templates", templateName),
369
- args
376
+ add(
377
+ copySingleFile(
378
+ path.join(SOURCE_TEMPLATES, templateName),
379
+ path.join(paths.resources, "templates", templateName),
380
+ args
381
+ )
370
382
  );
371
- installed += result.installed;
372
- skipped += result.skipped;
373
383
  }
374
384
 
375
- const mcpResult = copySingleFile(
376
- SOURCE_MCP_EXAMPLE,
377
- path.join(paths.resources, ".mcp.json.example"),
378
- args
379
- );
380
- installed += mcpResult.installed;
381
- skipped += mcpResult.skipped;
385
+ add(copySingleFile(SOURCE_MCP_EXAMPLE, path.join(paths.resources, ".mcp.json.example"), args));
382
386
  }
383
387
 
384
- return { installed, skipped };
388
+ return { rootPath, installed, overwritten, skipped, cleaned };
385
389
  }
386
390
 
387
391
  function detectInstallType() {
@@ -539,25 +543,63 @@ function runUpdate(args) {
539
543
  const packageDir = resolveInstalledPackageDir(installType);
540
544
  const versionAfter = packageDir ? readInstalledVersion(packageDir) : null;
541
545
  printUpdateChangeSummary(packageDir, versionBefore, versionAfter);
546
+
547
+ console.log(`\n${colors.cyan}${"─".repeat(56)}${colors.reset}`);
548
+ console.log(`${colors.cyan}Update Summary${colors.reset}`);
549
+ if (versionAfter && versionAfter !== versionBefore) {
550
+ console.log(` Package: ${versionBefore} → ${colors.green}${versionAfter}${colors.reset} (${installType} install)`);
551
+ } else if (versionAfter) {
552
+ console.log(` Package: already up to date at ${colors.green}v${versionAfter}${colors.reset} (${installType} install)`);
553
+ } else {
554
+ console.log(` Package: updated from v${versionBefore} (${installType} install; new version could not be read)`);
555
+ }
556
+ console.log(` Files: reinstalled with --force for ${selectedTools(args).join(", ")} (see Install Summary above)`);
557
+ console.log(` Verify: ${colors.cyan}akili doctor --tool ${args.tool}${colors.reset}`);
558
+ }
559
+
560
+ function summaryCounts(result) {
561
+ return `${colors.green}installed ${result.installed}${colors.reset} | overwritten ${result.overwritten} | ${colors.yellow}skipped ${result.skipped}${colors.reset}${result.cleaned ? ` | legacy cleaned ${result.cleaned}` : ""}`;
542
562
  }
543
563
 
544
564
  function runInstall(args) {
545
- let installed = 0;
546
- let skipped = 0;
565
+ const tools = selectedTools(args);
566
+ const results = [];
547
567
 
548
- for (const tool of selectedTools(args)) {
549
- const result = installTool(tool, args);
550
- installed += result.installed;
551
- skipped += result.skipped;
568
+ for (const tool of tools) {
569
+ results.push({ tool, ...installTool(tool, args) });
552
570
  }
553
571
 
554
- console.log(`\nDone. Installed: ${installed} | Skipped: ${skipped}`);
555
- if (skipped > 0 && !args.force) {
556
- console.log(`Use ${colors.yellow}--force${colors.reset} to overwrite existing files.`);
572
+ const totals = results.reduce(
573
+ (acc, r) => ({
574
+ installed: acc.installed + r.installed,
575
+ overwritten: acc.overwritten + r.overwritten,
576
+ skipped: acc.skipped + r.skipped,
577
+ cleaned: acc.cleaned + r.cleaned,
578
+ }),
579
+ { installed: 0, overwritten: 0, skipped: 0, cleaned: 0 }
580
+ );
581
+
582
+ console.log(`\n${colors.cyan}${"─".repeat(56)}${colors.reset}`);
583
+ console.log(`${colors.cyan}Install Summary${colors.reset} — akili-specs v${currentVersion}${args.dryRun ? ` ${colors.yellow}(dry-run: no files were written)${colors.reset}` : ""}`);
584
+ for (const r of results) {
585
+ console.log(` ${r.tool.toUpperCase().padEnd(12)} ${summaryCounts(r)}`);
586
+ console.log(` ${"".padEnd(12)} → ${r.rootPath}`);
587
+ }
588
+ if (results.length > 1) {
589
+ console.log(` ${"TOTAL".padEnd(12)} ${summaryCounts(totals)}`);
557
590
  }
558
591
 
559
- if (selectedTools(args).includes("opencode") && !args.dryRun) {
560
- console.log(`Restart ${colors.cyan}OpenCode${colors.reset} for installed commands and skills to be loaded.`);
592
+ console.log(`\n${colors.cyan}Next steps:${colors.reset}`);
593
+ if (totals.skipped > 0 && !args.force) {
594
+ console.log(` - ${totals.skipped} existing file(s) were preserved. Re-run with ${colors.yellow}--force${colors.reset} to overwrite them.`);
595
+ }
596
+ if (tools.includes("opencode") && !args.dryRun) {
597
+ console.log(` - Restart ${colors.cyan}OpenCode${colors.reset} for installed commands and skills to be loaded.`);
598
+ }
599
+ if (args.dryRun) {
600
+ console.log(` - Re-run without ${colors.yellow}--dry-run${colors.reset} to apply the changes above.`);
601
+ } else {
602
+ console.log(` - Verify the installation with ${colors.cyan}akili doctor --tool ${args.tool}${colors.reset}.`);
561
603
  }
562
604
  }
563
605
 
@@ -574,6 +616,9 @@ function runList() {
574
616
  RESOURCE_SCRIPTS.forEach((name) => console.log(` ${formatPath(path.join("scripts", name))}`));
575
617
  AGENT_TEMPLATES.forEach((name) => console.log(` ${formatPath(path.join("templates", name))}`));
576
618
  console.log(" .mcp.json.example");
619
+
620
+ const resourceCount = RESOURCE_SCRIPTS.length + AGENT_TEMPLATES.length + 1;
621
+ console.log(`\n${colors.cyan}Summary:${colors.reset} ${commands.length} commands | ${skills.length} skills | ${resourceCount} resources (akili-specs v${currentVersion})`);
577
622
  }
578
623
 
579
624
  function hasInstalledCommand(targetCommandsList, name) {
@@ -587,6 +632,7 @@ function hasInstalledCommand(targetCommandsList, name) {
587
632
 
588
633
  function doctorTool(tool, args) {
589
634
  const { rootPath, paths } = getToolRegistryInfo(tool, args);
635
+ let okCount = 0;
590
636
  let missing = 0;
591
637
  let fixed = 0;
592
638
 
@@ -597,6 +643,7 @@ function doctorTool(tool, args) {
597
643
  for (const command of listCommands()) {
598
644
  const ok = hasInstalledCommand(paths.commands, command);
599
645
  if (ok) {
646
+ okCount += 1;
600
647
  console.log(` ${colors.green}OK${colors.reset} ${command}`);
601
648
  } else {
602
649
  if (args.fix) {
@@ -617,6 +664,7 @@ function doctorTool(tool, args) {
617
664
  for (const skill of listSkills()) {
618
665
  const ok = fs.existsSync(path.join(paths.skills, skill, "SKILL.md"));
619
666
  if (ok) {
667
+ okCount += 1;
620
668
  console.log(` ${colors.green}OK${colors.reset} ${skill}`);
621
669
  } else {
622
670
  if (args.fix) {
@@ -646,6 +694,7 @@ function doctorTool(tool, args) {
646
694
  for (const check of resourceChecks) {
647
695
  const ok = fs.existsSync(check.dest);
648
696
  if (ok) {
697
+ okCount += 1;
649
698
  console.log(` ${colors.green}OK${colors.reset} ${check.dest}`);
650
699
  } else {
651
700
  if (args.fix) {
@@ -660,23 +709,41 @@ function doctorTool(tool, args) {
660
709
  }
661
710
  }
662
711
 
663
- return { missing, fixed };
712
+ return { rootPath, ok: okCount, missing, fixed };
664
713
  }
665
714
 
666
715
  function runDoctor(args) {
667
- let missingTotal = 0;
668
- let fixedTotal = 0;
669
-
716
+ const results = [];
717
+
670
718
  for (const tool of selectedTools(args)) {
671
- const { missing, fixed } = doctorTool(tool, args);
672
- missingTotal += missing;
673
- fixedTotal += fixed;
719
+ results.push({ tool, ...doctorTool(tool, args) });
720
+ }
721
+
722
+ const missingTotal = results.reduce((acc, r) => acc + r.missing, 0);
723
+ const fixedTotal = results.reduce((acc, r) => acc + r.fixed, 0);
724
+
725
+ console.log(`\n${colors.cyan}${"─".repeat(56)}${colors.reset}`);
726
+ console.log(`${colors.cyan}Doctor Summary${colors.reset} — akili-specs v${currentVersion}`);
727
+ for (const r of results) {
728
+ const status =
729
+ r.missing > 0
730
+ ? `${colors.red}INCOMPLETE${colors.reset}`
731
+ : r.fixed > 0
732
+ ? `${colors.cyan}REPAIRED${colors.reset}`
733
+ : `${colors.green}HEALTHY${colors.reset}`;
734
+ console.log(` ${r.tool.toUpperCase().padEnd(12)} ${status} ${colors.green}ok ${r.ok}${colors.reset} | ${colors.red}missing ${r.missing}${colors.reset} | fixed ${r.fixed}`);
735
+ console.log(` ${"".padEnd(12)} → ${r.rootPath}`);
674
736
  }
675
737
 
676
- console.log(`\nDone. Missing: ${missingTotal} | Fixed: ${fixedTotal}`);
677
738
  if (missingTotal > 0) {
678
- console.log(`Run ${colors.cyan}akili doctor --fix${colors.reset} to auto-repair missing files.`);
739
+ console.log(`\n${colors.cyan}Next steps:${colors.reset}`);
740
+ console.log(` - Run ${colors.cyan}akili doctor --tool ${args.tool} --fix${colors.reset} to auto-repair the ${missingTotal} missing file(s).`);
741
+ console.log(` - Or run ${colors.cyan}akili update${colors.reset} to refresh the package and reinstall everything.`);
679
742
  process.exitCode = 1;
743
+ } else if (fixedTotal > 0) {
744
+ console.log(`\nAll issues repaired: ${fixedTotal} file(s) restored.`);
745
+ } else {
746
+ console.log(`\nAll checks passed. Your installation is complete and healthy.`);
680
747
  }
681
748
  }
682
749
 
package/docs/cli.md CHANGED
@@ -56,6 +56,13 @@ akili install --tool both --local
56
56
  | `akili doctor` | Check whether expected files are installed |
57
57
  | `akili help` | Show help |
58
58
 
59
+ Every command closes with a clear end-of-run summary:
60
+
61
+ - **`install`** — an **Install Summary** with per-tool `installed | overwritten | skipped` counts (plus legacy cleanup), target paths, totals for multi-tool installs, a dry-run banner when `--dry-run` is used, and contextual next steps (`--force` hint, OpenCode restart, `akili doctor` verification).
62
+ - **`doctor`** — a **Doctor Summary** with a per-tool `HEALTHY | REPAIRED | INCOMPLETE` status, `ok | missing | fixed` counts, and repair suggestions (`--fix` or `akili update`).
63
+ - **`update`** — an **Update Summary** with the version change (`before → after`), install type, and the verification command, after the changelog of what changed.
64
+ - **`list`** — a totals line: commands, skills, resources, and the package version.
65
+
59
66
  ## Options
60
67
 
61
68
  | Option | Applies To | Purpose |
@@ -12,6 +12,7 @@ The installable source files live in `.claude/skills/*/SKILL.md`. These pages ar
12
12
  | [`api-design-principles`](api-design-principles.md) | REST and GraphQL API design and review | `/akili-constitution`, `/akili-specify`, `/akili-validate` |
13
13
  | [`aws-serverless`](aws-serverless.md) | Lambda, API Gateway, DynamoDB, SQS/SNS, SAM/CDK | `/akili-constitution`, `/akili-specify`, `/akili-execute` |
14
14
  | [`brainstorming`](brainstorming.md) | Clarifying ideas, scope, options, and trade-offs before implementation | `/akili-propose`, `/akili-specify` |
15
+ | [`cognitive-doc-design`](cognitive-doc-design.md) | Writing human-facing docs that reduce cognitive load (lead with the answer, progressive disclosure, tables over prose) | `/akili-constitution`, `/akili-specify`, `/akili-execute` (PR docs), `/akili-archive` |
15
16
  | [`error-handling-patterns`](error-handling-patterns.md) | Exceptions, Result patterns, graceful degradation, reliability | `/akili-specify`, `/akili-execute`, `/akili-validate` |
16
17
  | [`frontend-design`](frontend-design.md) | Distinctive frontend UI and UX implementation | `/akili-constitution`, `/akili-specify`, `/akili-execute`, `/akili-test` |
17
18
  | [`gsap-core`](gsap-core.md) | Core GSAP tweens, easing, stagger, responsive and reduced-motion animation | `/akili-specify`, `/akili-execute` |
@@ -24,7 +25,7 @@ The installable source files live in `.claude/skills/*/SKILL.md`. These pages ar
24
25
  | [`gsap-utils`](gsap-utils.md) | GSAP utilities such as clamp, mapRange, random, snap, wrap | `/akili-execute` |
25
26
  | [`kaizen`](kaizen.md) | Bounded continuous-improvement retrospective (Measure → Learn → Standardize → Record); authored by Juan Carlos Cadavid — jcadavid.com | `/akili-archive` |
26
27
  | [`nestjs-expert`](nestjs-expert.md) | NestJS modules, DI, guards, interceptors, testing, TypeORM/Mongoose | `/akili-specify`, `/akili-execute`, `/akili-test`, `/akili-validate` |
27
- | [`product-manager-toolkit`](product-manager-toolkit.md) | Product discovery, PRDs, prioritization, customer interview analysis | `/akili-constitution`, `/akili-propose`, `/akili-specify` |
28
+ | [`product-manager-toolkit`](product-manager-toolkit.md) | Product discovery, PRDs, prioritization, customer interview analysis (AKILI-adapted: canonical PRD structure, RICE for scope-chunk ordering) | `/akili-constitution`, `/akili-propose`, `/akili-specify` |
28
29
  | [`react-doctor`](react-doctor.md) | React diagnostics after changes | `/akili-test`, `/akili-validate` |
29
30
  | [`seo-audit`](seo-audit.md) | Technical, on-page, and international SEO audits with a standard finding format | `/akili-seo`, `/akili-validate` |
30
31
  | [`shadcn-ui`](shadcn-ui.md) | shadcn/ui components, forms, themes, Tailwind integration | `/akili-specify`, `/akili-execute`, `/akili-validate` |
@@ -0,0 +1,31 @@
1
+ # `cognitive-doc-design`
2
+
3
+ ## Purpose
4
+
5
+ Designs documentation that reduces cognitive load, using six patterns: lead with the answer, progressive disclosure, chunking, signposting, recognition over recall, and review empathy. AKILI generates many human-facing documents (PRD, TRD, requirements, reports, summaries) — this skill defines how to write them so readers scan, understand, and verify quickly. Authored by gentleman-programming (Apache-2.0).
6
+
7
+ ## Use When
8
+
9
+ - Writing or upgrading any human-facing AKILI document: PRD, UX/UI design, TRD, requirements, design, reports, archive summaries.
10
+ - Writing PR descriptions and review notes during `/akili-execute` (its review-empathy rules reduce reviewer burnout).
11
+ - Any doc that currently feels long, dense, or hard to scan.
12
+
13
+ ## Core Rules
14
+
15
+ - Put the decision, action, or outcome first — context comes after.
16
+ - Start with the happy path, then details, edge cases, and references.
17
+ - Group related information into small sections; keep flat lists short.
18
+ - Use headings, labels, callouts, and summaries as signposts.
19
+ - Prefer tables, checklists, examples, and templates over prose that must be remembered.
20
+ - For PRs: state what to review first, what is out of scope, and link chained PRs.
21
+
22
+ ## Best Paired Commands
23
+
24
+ - `/akili-constitution` — writing `docs/prd.md`, the UX/UI design doc, and the TRD.
25
+ - `/akili-specify` — writing `requirements.md`, `design.md`, and `tasks.md`.
26
+ - `/akili-execute` — writing PR descriptions and review notes.
27
+ - `/akili-archive` — writing `archive-summary.md` and Kaizen log entries (one-point lessons are recognition over recall).
28
+
29
+ ## Source
30
+
31
+ - `../../.claude/skills/cognitive-doc-design/SKILL.md`
@@ -2,20 +2,20 @@
2
2
 
3
3
  ## Purpose
4
4
 
5
- Supports product management work, including PRDs, customer interview analysis, RICE prioritization, discovery frameworks, requirements, and go-to-market thinking.
5
+ Supports product management work, including PRDs, customer interview analysis, RICE prioritization, discovery frameworks, requirements, and go-to-market thinking. Adapted for AKILI-SPECS: its **AKILI-SPECS Integration** section maps each tool to one precise moment in the flow, and the AKILI 9-section PRD structure is canonical over the toolkit's own templates.
6
6
 
7
7
  ## Use When
8
8
 
9
- - Creating or improving `docs/prd.md`.
10
- - Clarifying personas, goals, scope, success metrics, or non-goals.
11
- - Prioritizing features or deciding whether work should proceed.
9
+ - Creating or improving `docs/prd.md` (the AKILI structure wins; the toolkit fills its sections well — North Star Metric, jobs-to-be-done, Hypothesis Template).
10
+ - Clarifying personas, goals, scope, success metrics, or non-goals (`/akili-constitution` Step 2 uses its Customer Interview Guide as the question script; the interview analyzer extracts pain points from transcripts).
11
+ - Ordering scope chunks with RICE or MoSCoW when `/akili-propose` or `/akili-specify` split an epic into multiple specs.
12
12
  - Turning discovery into requirements.
13
13
 
14
14
  ## Best Paired Commands
15
15
 
16
- - `/akili-constitution` for project PRD baseline.
17
- - `/akili-propose` for intent and scope.
18
- - `/akili-specify` for behavior requirements.
16
+ - `/akili-constitution` for business-context questions (Step 2) and the project PRD baseline (Step 3).
17
+ - `/akili-propose` for intent, scope, and chunk ordering.
18
+ - `/akili-specify` for behavior requirements and split-spec ordering.
19
19
 
20
20
  ## Source
21
21
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "akili-specs",
3
- "version": "2.6.0",
3
+ "version": "2.7.1",
4
4
  "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
5
5
  "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
6
6
  "repository": {
@@ -46,5 +46,6 @@
46
46
  "engines": {
47
47
  "node": ">=18.0.0"
48
48
  },
49
- "license": "MIT"
49
+ "license": "MIT",
50
+ "author": "Juan Carlos Cadavid (https://jcadavid.com)"
50
51
  }