@anionzo/skill 1.4.0 → 1.7.0

package/skills/extract/SKILL.md

@@ -0,0 +1,201 @@
+# Extract
+
+## Purpose
+
+Extract reusable patterns, significant decisions, and failure learnings from completed work into documentation that compounds knowledge over time.
+
+This skill exists to turn individual task outcomes into organizational memory — not just code patterns, but also the decisions and mistakes that are expensive to repeat.
+
+It also covers session handoff when work is not yet complete: compress the active task state into the smallest high-signal baton pass so a new session can continue without rereading everything.
+
+## When To Use
+
+Load this skill when:
+
+- a task or feature is complete and had notable learnings
+- a debugging session revealed a pattern worth remembering
+- a decision was made that future work should know about
+- a mistake was made that should not be repeated
+- the user says "extract learnings", "document what we learned", or "capture this pattern"
+- the user asks "what did we do so far?" or "summarize where we are"
+- work is being handed to another session or agent
+- the current session is approaching its context limit
+
+Skip this skill when work was routine with no surprises, novel patterns, or meaningful in-progress state to carry forward.
+
+## Workflow
+
+1. Identify the source of value:
+   - completed task or debugging session -> durable learning extraction
+   - unfinished task or near-full context -> session handoff
+2. If extracting durable knowledge, analyze across three categories: patterns, decisions, and failures.
+3. If preparing a handoff, compress the active task into: goal, done so far, current state, locked decisions, open risks, and next best action.
+4. Check for existing documentation that should be updated (avoid duplicates).
+5. Create or update the right artifact:
+   - durable knowledge documentation
+   - temporary handoff summary
+6. Promote critical learnings that would save significant time if known in advance.
+
+## Session Handoff Mode
+
+When the task is not complete, create a high-signal baton pass for the next session.
+
+Include:
+
+- **Goal** — what is actively being worked on
+- **Done So Far** — completed changes, validation, commits, and approved decisions
+- **Current State** — what is verified, what is still in progress, and any dirty worktree notes
+- **Locked Decisions** — decisions that should not be re-litigated unless the user reopens them
+- **Open Questions / Risks** — blockers, uncertainty, or easy-to-miss constraints
+- **Next Best Action** — the single clearest next step
+- **Handoff Payload** — a compact 5-15 line summary for copy-paste into a new session
+
+Compression rules:
+
+- include only details that save meaningful time in the next session
+- prefer concrete file paths, commands, commits, and verification state when relevant
+- do not replay the whole conversation
+- keep temporary task state separate from durable knowledge
+
+## Three-Category Analysis
+
+### Patterns
+
+Reusable approaches worth standardizing:
+
+- **Code patterns** — new utilities, abstractions, integration techniques
+- **Architecture patterns** — structural decisions that worked
+- **Process patterns** — workflow approaches that saved time
+
+For each pattern, document:
+- What it is
+- When to use it
+- A concrete example
+- Where it was first used
+
+### Decisions
+
+Significant choices and their outcomes:
+
+- **GOOD_CALL** — decisions that proved correct or saved time
+- **BAD_CALL** — decisions that required rework
+- **SURPRISE** — things that turned out differently than expected
+- **TRADEOFF** — conscious choices where alternatives were considered
+
+For each decision, document:
+- What was chosen
+- What was rejected
+- How it played out
+- Recommendation for future work
+
+### Failures
+
+Mistakes and wasted effort worth preventing:
+
+- Bugs introduced and their root causes
+- Wrong assumptions that required backtracking
+- Missing prerequisites discovered mid-execution
+- Test gaps that allowed regressions
+
+For each failure, document:
+- What went wrong
+- Root cause (not just symptom)
+- Time cost estimate
+- How to prevent it
+
+## Knowledge Document Template
+
+```markdown
+## Patterns
+
+### [Pattern Name]
+- **What:** [description]
+- **When to use:** [applicable conditions]
+- **Example:** [concrete code or workflow example]
+- **Source:** [task or feature reference]
+
+## Decisions
+
+### [Decision]
+- **Chose:** [what was chosen]
+- **Over:** [what was rejected]
+- **Tag:** GOOD_CALL / BAD_CALL / SURPRISE / TRADEOFF
+- **Outcome:** [how it played out]
+- **Recommendation:** [for future work]
+
+## Failures
+
+### [Failure]
+- **What went wrong:** [description]
+- **Root cause:** [not just symptom]
+- **Time lost:** [estimate]
+- **Prevention:** [what to do differently]
+```
+
+## Extraction Rules
+
+- Extract patterns, decisions, AND failures — not just code patterns.
+- Search for existing docs before creating new ones — update instead of duplicating.
+- Link extracted knowledge back to its source.
+- Only document genuinely reusable knowledge — do not fabricate findings.
+- A short learning with 2 genuine entries is better than a long doc with invented ones.
+
+## Critical Learning Promotion
+
+For findings that meet ALL criteria:
+- Affects more than one future feature
+- Would cause 30+ minutes wasted effort if unknown
+- Is generalizable, not implementation-specific
+
+These should be marked as critical and placed where they will be seen at the start of future work sessions.
+
+**Calibration:** Do NOT promote everything. If critical learnings grow past 20-30 entries, they become noise. Only promote learnings that would have saved 30+ minutes if known in advance.
+
+## Output Format
+
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — what knowledge was extracted, updated, or intentionally not extracted
+2. **Key Details:**
+   - what was extracted or handed off
+   - whether this was durable knowledge or temporary task state
+   - whether docs were created or updated
+   - whether critical learnings were promoted
+   - where the canonical knowledge now lives
+3. **Next Action** — only when findings lead somewhere:
+   - extracted from completed task → `commit` if changes pending
+   - task is not complete but should continue later → name the primary next skill
+   - no clear handoff → stop after the result
+
+## No-Op Case
+
+If the work was too routine to generalize, say so explicitly and do not force a new document. Do NOT fabricate findings. If the task ran smoothly with no surprises, write that.
+
+## Red Flags
+
+- only extracting code patterns, ignoring decisions and failures
+- replaying the full session instead of compressing it
+- promoting everything as critical (noise kills the learning loop)
+- writing generic learnings like "test more carefully" (worthless)
+- fabricating findings when the task was straightforward
+- not checking existing docs before creating duplicates
+- extracting implementation-specific details that will never be reused
+
+## Checklist
+
+- [ ] Three categories analyzed (patterns, decisions, failures)
+- [ ] Or handoff state compressed (goal, done, current state, risks, next action)
+- [ ] Existing docs checked for duplicates
+- [ ] Knowledge is genuinely generalizable
+- [ ] Includes concrete examples (for patterns)
+- [ ] Links back to source
+- [ ] Critical learnings promoted (if applicable)
+
+## Done Criteria
+
+This skill is complete when either:
+
+- the three-category analysis is done and any durable findings worth preserving are documented in the appropriate location, or
+- the in-progress task has been compressed into a clear handoff that a new session can continue from without redoing expensive analysis.
+
+If nothing worth extracting or handing off was found, an explicit "no-op" statement is the valid completion.

package/skills/extract/examples.md

@@ -0,0 +1,47 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+We just finished the auth refactor. Extract what we learned.
+```
+
+Expected result:
+
+- analyze the completed work across three categories
+- document patterns, decisions, and failures
+- promote critical learnings if applicable
+
+Sample completed output:
+
+```
+Goal/Result: Extracted 2 patterns, 1 decision, and 1 failure from the auth refactor.
+
+Key Details:
+  Patterns:
+  1. Provider Registry Pattern — centralized auth provider registration
+     in src/auth/registry.ts. New providers implement AuthProvider
+     interface and register in one place. Reusable for any plugin system.
+  2. Token Rotation Pattern — refresh tokens are rotated on each use
+     (one-time use). Prevents replay attacks.
+
+  Decisions:
+  1. TRADEOFF: Chose passport.js over custom auth middleware.
+     - Pros: ecosystem support, community maintenance
+     - Cons: callback-heavy API, harder to test
+     - Outcome: Worked well for OAuth but added friction for custom flows
+     - Recommendation: Use passport for OAuth, custom middleware for API keys
+
+  Failures:
+  1. Assumed session store was thread-safe — it was not.
+     - Root cause: Redis client was shared without connection pooling
+     - Time lost: ~4 hours debugging intermittent auth failures
+     - Prevention: Always verify concurrent access patterns for shared state
+
+  Critical learning promoted: Redis connection pooling requirement.
+  (Would have saved 4+ hours if known in advance.)
+
+Next Action: No follow-up needed — knowledge documented.
+```

package/skills/extract/meta.yaml

@@ -0,0 +1,33 @@
+name: extract
+version: 0.2.0
+category: knowledge
+summary: Extract durable learnings from completed work, or compress in-progress task state into a high-signal handoff for the next session.
+summary_vi: "Trích xuất bài học bền vững từ công việc đã xong, hoặc nén trạng thái công việc đang dở thành handoff sắc gọn cho session tiếp theo."
+triggers:
+  - extract learnings from this task
+  - document what we learned
+  - capture this pattern
+  - what did we learn
+  - what did we do so far
+  - summarize where we are
+  - prepare a handoff
+  - context is getting full
+inputs:
+  - completed task, unfinished task, or feature
+  - code changes, debugging session, or current task state
+outputs:
+  - patterns documented
+  - decisions recorded
+  - failures captured
+  - critical learnings promoted
+  - handoff payload for the next session
+constraints:
+  - search existing docs before creating new ones
+  - do not fabricate findings
+  - use three-category analysis for durable knowledge
+  - compress instead of replaying the whole session for handoffs
+related_skills:
+  - using-skills
+  - commit
+  - debug
+  - research

package/skills/extract/references/output-template.md

@@ -0,0 +1,24 @@
+## Goal/Result
+
+- Knowledge extracted:
+
+## Key Details
+
+### Patterns
+- Pattern 1:
+
+### Decisions
+- Decision 1:
+
+### Failures
+- Failure 1:
+
+### Critical Learnings Promoted
+-
+
+### Docs Created/Updated
+-
+
+## Next Action
+
+- Recommended follow-up:

package/skills/feature-delivery/SKILL.md

@@ -19,11 +19,16 @@ Load this skill when the user wants code changed to add or update behavior.
 
 ## Output Format
 
-- goal and scope
-- chosen approach
-- files changed
-- verification performed
-- follow-up or risk note
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — the feature implemented and its status
+2. **Key Details:**
+   - goal and scope
+   - chosen approach
+   - files changed
+   - verification performed
+   - follow-up or risk note
+3. **Next Action** — `verification-before-completion` to confirm, then `code-review` or `commit`; if pausing mid-task, use `extract` in handoff mode
 
 ## Red Flags
 
@@ -37,3 +42,5 @@ Load this skill when the user wants code changed to add or update behavior.
 This skill is complete when the feature works as intended, the change is verified with the most relevant check available, and the outcome is summarized clearly.
 
 Before declaring done, run `verification-before-completion` to confirm the claim is backed by fresh evidence.
+
+If the task must pause before completion, use `extract` in handoff mode so the next session can resume without repeating the implementation analysis.

package/skills/feature-delivery/meta.yaml

@@ -20,7 +20,12 @@ constraints:
   - ask only one blocking question when necessary
 related_skills:
   - using-skills
+  - brainstorming
   - planning
-  - repo-onboarding
+  - research
+  - debug
   - verification-before-completion
   - code-review
+  - docs-writer
+  - extract
+  - test-driven-development

package/skills/planning/SKILL.md

@@ -2,10 +2,12 @@
 
 ## Purpose
 
-Produce an execution-ready plan before code changes begin.
+Produce an execution-ready plan before code changes begin. Each step must be concrete enough that another engineer could execute it without inventing missing context.
 
 This skill exists to make planning explicit, especially for multi-file or non-trivial work.
 
+It also covers go mode when the user wants an approved spec or clear task executed end-to-end with minimal review gates.
+
 ## When To Use
 
 Load this skill when:
@@ -15,38 +17,139 @@ Load this skill when:
 - the change touches APIs, data flow, persistence, or architecture boundaries
 - the user explicitly asks for a plan
 - implementation risk is high enough that code should not start immediately
+- the user says "run all", "go mode", "execute everything", or wants one continuous plan-to-commit flow
 
 ## Workflow
 
 1. Restate the goal in user-visible terms.
-2. Define the scope boundary:
-   - what is in scope
-   - what is out of scope
-3. Inspect the existing code paths and patterns that the work should follow.
+2. Define the scope boundary (in/out).
+3. Inspect existing code paths and patterns the work should follow.
 4. Choose the smallest viable approach that fits the repo.
-5. Break the work into ordered steps.
+5. Break the work into ordered, bite-sized steps.
 6. Call out risks, assumptions, and missing decisions.
 7. Define how the work will be verified.
-8. End with the next implementation skill to invoke.
+8. Run the pre-execution plan check.
+9. Run the self-review.
+10. Present for approval.
+11. End with the next implementation skill to invoke.
+
+## Go Mode
+
+When the user wants an approved spec or clear task executed with minimal review gates, planning enters go mode:
+
+1. Validate that requirements are clear enough to implement.
+2. Break the work into ordered implementation tasks.
+3. Map each task to acceptance criteria or explicit outcomes.
+4. Plan and execute each task in dependency order.
+5. Verify after each task.
+6. Run full verification at the end.
+7. Prepare a single commit proposal and ask the user before committing.
+
+If the scope is too large for one context window, checkpoint progress and resume later rather than continuing blindly.
+
+## Bite-Sized Task Granularity
+
+Each step should be one action, completable in 2-5 minutes:
+
+- "Write the failing test for X" — one step
+- "Run the test, confirm it fails" — one step
+- "Implement the minimal code to pass the test" — one step
+- "Run the tests, confirm all pass" — one step
+- "Commit" — one step
+
+If a step requires reading more than 10 files or touching more than 5 files, split it.
+
+If the total plan exceeds approximately 8 steps, consider splitting into subtasks.
+
+## No Placeholders
+
+Every step must contain the actual content an engineer needs. These are plan failures — never write them:
+
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" (without describing which tests)
+- "Similar to Step N" (repeat the specifics — the engineer may read steps out of order)
+- Steps that describe what to do without showing which files and what changes
+- References to types, functions, or methods not defined in any step
+
+**Every step must name the files, modules, or surfaces that change.**
+
+## Pre-Execution Plan Check
+
+Before presenting the plan for approval, verify plan quality across four dimensions:
+
+### AC Coverage
+- Every requirement from the task should map to at least one plan step.
+- Every plan step should contribute to at least one acceptance criterion.
+- Flag any AC that no plan step addresses.
+
+### Scope Sizing
+- Each step should be completable in a single implementation session (2-5 min).
+- Flag steps that are too large and recommend splitting.
+
+### Dependency Check
+- Steps should be in logical order (foundational first, dependent last).
+- Flag circular dependencies between steps.
+- Flag steps that assume undocumented context.
+
+### Risk Assessment
+- Steps involving new external dependencies — flag as higher risk.
+- Steps touching core/shared modules — flag blast radius.
+- Steps with no test coverage in the plan — flag.
+
+**Report issues inline with the plan:**
+
+```
+Plan:
+1. Write failing test for auth middleware
+2. Implement auth middleware
+3. Update existing routes
+  Plan check: AC-3 (rate limiting) not covered by any step
+  Plan check: Step 3 touches 7 files — consider splitting
+```
+
+Fix issues before presenting for approval. If unfixable, surface them explicitly so the user can decide.
+
+## Self-Review
+
+After writing the complete plan, review it with fresh eyes:
+
+1. **Requirement coverage:** Skim each requirement. Can you point to a step that implements it? List any gaps.
+2. **Placeholder scan:** Search the plan for any of the patterns from the "No Placeholders" section. Fix them.
+3. **Name consistency:** Do the types, method signatures, and property names used in later steps match what is defined in earlier steps?
+4. **File path accuracy:** Are all file paths plausible given the project structure?
+
+If you find issues, fix them inline before presenting the plan.
 
 ## Output Format
 
-- goal
-- scope
-- existing patterns or files to follow
-- proposed approach
-- ordered implementation steps
-- risks and assumptions
-- verification plan
-- next skill to invoke
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — the plan and whether approval is pending
+2. **Key Details:**
+   - scope (in/out)
+   - existing patterns or files to follow
+   - proposed approach
+   - ordered implementation steps (bite-sized, no placeholders)
+   - pre-execution check results (AC coverage, scope sizing, dependency, risk)
+   - self-review results
+   - risks and assumptions
+   - verification plan
+3. **Next Action** — after approval:
+   - `feature-delivery` for implementation
+   - `test-driven-development` if TDD approach preferred
+   - `brainstorming` if requirements need more definition first
+   - if the user wants one continuous execution run: continue in go mode under `planning`
 
 ## Planning Rules
 
 - Keep the plan concrete enough that another engineer could execute it.
 - Prefer a small number of meaningful steps over a long task dump.
-- Name the files, modules, or surfaces likely to change when possible.
+- Name the files, modules, or surfaces likely to change in every step.
 - Make uncertainty explicit instead of hiding it in vague language.
 - Do not start coding inside the plan.
+- Complete code in every step — if a step changes code, describe the change specifically.
+- DRY, YAGNI — do not plan features that are not required.
 
 ## Red Flags
 
@@ -55,7 +158,33 @@ Load this skill when:
 - turning the plan into a full design doc for a small change
 - leaving verification unspecified
 - mixing code edits into the planning phase
+- skipping the pre-execution check
+- presenting a plan where ACs are not covered by any step
+- steps that say "add appropriate X" without specifying what X is
+- steps referencing functions or types not defined in any previous step
+
+## Checklist
+
+- [ ] Goal restated in user-visible terms
+- [ ] Scope boundary defined (in/out)
+- [ ] Existing patterns inspected
+- [ ] Approach chosen (smallest viable)
+- [ ] Steps ordered, bite-sized (2-5 min each), with file paths
+- [ ] No placeholders in any step
+- [ ] Pre-execution check passed:
+  - [ ] AC coverage verified
+  - [ ] Scope sizing reasonable
+  - [ ] Dependencies ordered correctly
+  - [ ] Risks flagged
+- [ ] Self-review passed:
+  - [ ] Requirement coverage
+  - [ ] Placeholder scan
+  - [ ] Name consistency
+  - [ ] File path accuracy
+- [ ] Verification plan defined
+- [ ] Plan presented for approval
+- [ ] Next skill identified
 
 ## Done Criteria
 
-This skill is complete when the implementation path, risks, and verification steps are clear enough to hand off to `feature-delivery`, `refactor-safe`, or to a bounded bug fix.
+This skill is complete when the implementation path, risks, and verification steps are clear enough to hand off to `feature-delivery`, `refactor-safe`, or `test-driven-development` — or, in go mode, when the work has been planned, executed, verified, and brought to a commit gate. The pre-execution check and self-review must have been run with all findings addressed or explicitly surfaced.

package/skills/planning/meta.yaml

@@ -1,29 +1,41 @@
 name: planning
-version: 0.1.0
+version: 0.4.0
 category: planning
-summary: Turn a request into an execution-ready plan with scope, approach, risks, and verification before code changes begin.
-summary_vi: Biến request thành plan sẵn sàng thực thi với phạm vi, cách tiếp cận, rủi ro, và xác minh trước khi bắt đầu code.
+summary: Execution-ready plans with bite-sized steps, no placeholders, self-review, pre-execution validation, and optional go-mode execution.
+summary_vi: "Plan sẵn sàng thực thi với bước nhỏ gọn, không placeholder, tự review, kiểm tra trước thực thi, và có thể chạy theo go mode."
 triggers:
   - make a plan
   - think through the implementation first
   - prepare before coding
+  - run all
+  - go mode
+  - execute everything
 inputs:
   - user request
   - relevant repo context
   - existing patterns and constraints
+  - optional approved spec or explicit requirements
 outputs:
-  - scope
+  - scope (in/out)
   - approach
-  - file plan
+  - bite-sized ordered steps with file paths
+  - pre-execution check results
+  - self-review results
   - verification plan
+  - optional go-mode task execution and commit proposal
 constraints:
   - keep the plan concrete and bounded
   - separate planning from implementation
+  - no placeholders in any step
+  - each step names files and is 2-5 min
+  - run pre-execution check and self-review before presenting
 related_skills:
   - using-skills
   - brainstorming
-  - repo-onboarding
+  - research
+  - debug
   - feature-delivery
-  - bug-triage
   - refactor-safe
+  - code-review
+  - test-driven-development
   - verification-before-completion

package/skills/refactor-safe/SKILL.md

@@ -32,13 +32,16 @@ Do not use this skill when the intent is also to change behavior. Separate the r
 
 ## Output Format
 
-- goal and scope boundary
-- behavior contract
-- coverage check before
-- steps taken
-- coverage result after
-- behavioral drift check
-- handoff or follow-up
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — the refactor performed and whether behavior is preserved
+2. **Key Details:**
+   - goal and scope boundary
+   - behavior contract
+   - coverage check before and after
+   - steps taken
+   - behavioral drift check result
+3. **Next Action** — `verification-before-completion` to confirm, then `commit`
 
 ## Red Flags