@anionzo/skill 1.4.0 → 1.6.0

package/skills/planning/SKILL.md

@@ -2,7 +2,7 @@
 
 ## 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.
 
@@ -19,34 +19,119 @@ Load this skill when:
 ## 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.
+
+## 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
 
 ## 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 +140,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`. The pre-execution check and self-review must have been run with all findings addressed or explicitly surfaced.

package/skills/planning/meta.yaml

@@ -1,8 +1,8 @@
 name: planning
-version: 0.1.0
+version: 0.3.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, and pre-execution validation.
+summary_vi: "Plan sẵn sàng thực thi với bước nhỏ gọn, không placeholder, tự review, và kiểm tra trước thực thi."
 triggers:
   - make a plan
   - think through the implementation first
@@ -12,18 +12,27 @@ inputs:
   - relevant repo context
   - existing patterns and constraints
 outputs:
-  - scope
+  - scope (in/out)
   - approach
-  - file plan
+  - bite-sized ordered steps with file paths
+  - pre-execution check results
+  - self-review results
   - verification plan
 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
+  - go-pipeline
   - 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
 

package/skills/repo-onboarding/SKILL.md

@@ -30,13 +30,17 @@ Load this skill when:
 
 ## Output Format
 
-- project purpose
-- architecture summary
-- major components and responsibilities
-- important commands or workflows
-- notable conventions or constraints
-- open questions
-- recommended next reads
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — the repo understood and key findings
+2. **Key Details:**
+   - project purpose
+   - architecture summary
+   - major components and responsibilities
+   - important commands or workflows
+   - notable conventions or constraints
+   - open questions
+3. **Next Action** — `planning` (to plan a change), `research` (to go deeper on a topic), or `docs-writer` (to update documentation)
 
 ## Red Flags
 

package/skills/repo-onboarding/meta.yaml

@@ -20,4 +20,6 @@ constraints:
 related_skills:
   - using-skills
   - planning
+  - research
+  - feature-delivery
   - docs-writer

package/skills/research/SKILL.md

@@ -0,0 +1,100 @@
+# Research
+
+## Purpose
+
+Understand existing code, patterns, and decisions before writing new code.
+
+This skill exists to prevent implementing from scratch what already exists, and to surface constraints that would otherwise be discovered mid-implementation.
+
+## When To Use
+
+Load this skill when:
+
+- exploring a codebase before starting a task
+- looking for existing patterns, utilities, or conventions to follow
+- trying to understand how a feature or subsystem works
+- the implementation approach depends on what already exists
+- the user says "research this", "look into", or "what do we have for X"
+
+Skip this skill when you already have clear context and the task is straightforward.
+
+## Workflow
+
+1. State what is being researched and why.
+2. Search in this order:
+   - project documentation (READMEs, docs/, wikis)
+   - existing code paths and implementations
+   - adjacent tests, validation, and configuration
+   - related issues, PRs, or commit history
+3. For each finding, note:
+   - what exists and where
+   - whether it is reusable, needs adaptation, or is irrelevant
+   - any conventions or constraints it reveals
+4. Identify gaps — what does NOT exist that the task needs.
+5. Summarize findings with concrete recommendations.
+
+## Search Techniques
+
+Use the most efficient search method for the situation:
+
+```
+# Find files by name pattern
+find . -name "*<pattern>*" -type f | grep -v node_modules | head -20
+
+# Search code for patterns
+grep -r "<pattern>" --include="*.ts" -l | head -20
+
+# Check recent changes to a file
+git log --oneline -10 -- <file>
+
+# Find related tests
+find . -name "*<topic>*test*" -o -name "*test*<topic>*" | head -10
+```
+
+Read the actual files — do not guess from filenames alone.
+
+## Output Format
+
+Present findings using the Shared Output Contract:
+
+1. **Goal/Result** — what was researched and the key conclusion
+2. **Key Details:**
+   - concrete files or docs found
+   - what is reusable vs what is missing
+   - architecture or convention constraints discovered
+   - patterns that new code should follow
+3. **Next Action** — recommend a follow-up only when findings clearly lead somewhere:
+   - research for an active task → `planning`
+   - research revealed a gap → `brainstorming`
+   - no clear handoff → stop after findings
+
+## Research Rules
+
+- Search before assuming nothing exists.
+- Read the actual code, not just the file tree.
+- State explicitly when no existing pattern is found rather than implying one exists.
+- If docs and code disagree, call out the mismatch.
+- If the research surface is too large, focus on the most relevant subset and note what was not covered.
+- Do not expand the original question into unrelated exploration.
+
+## Red Flags
+
+- skipping the search and going straight to implementation
+- reading filenames without opening the files
+- reporting vague findings like "there seems to be something related"
+- expanding research scope without noting the expansion
+- treating absence of evidence as evidence of absence
+
+## Checklist
+
+- [ ] Research topic stated
+- [ ] Documentation searched
+- [ ] Existing code patterns found (or explicitly noted as absent)
+- [ ] Related tests and config checked
+- [ ] Findings include concrete file paths
+- [ ] Reusable vs missing clearly separated
+- [ ] Recommendations are actionable
+
+## Done Criteria
+
+This skill is complete when the findings are concrete enough to inform the next step — whether that is planning, implementation, or a decision that more information is needed. Every finding should include a file path or explicit "not found" statement.

package/skills/research/examples.md

@@ -0,0 +1,79 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+How does our auth system work? I need to add a new OAuth provider.
+```
+
+Expected result:
+
+- search for auth-related files, patterns, and documentation
+- identify existing OAuth implementations and patterns
+- note what is reusable and what needs to be built
+
+Sample completed output:
+
+```
+Goal/Result: Researched the auth system to understand how to add a new OAuth provider.
+
+Key Details:
+- Existing implementations:
+  - src/auth/providers/google.ts — Google OAuth using passport-google-oauth20
+  - src/auth/providers/github.ts — GitHub OAuth using passport-github2
+  - src/auth/strategy.ts — Base strategy wrapper, all providers follow this pattern
+  - src/auth/callback.ts — Shared callback handler for all OAuth flows
+- Patterns found:
+  - Each provider is a separate file in src/auth/providers/
+  - All providers implement the AuthProvider interface from src/auth/types.ts
+  - Callback URL pattern: /auth/{provider}/callback
+  - Config loaded from environment variables: AUTH_{PROVIDER}_CLIENT_ID, AUTH_{PROVIDER}_SECRET
+- Gaps:
+  - No generic OAuth2 provider — each is implemented individually
+  - No tests for the OAuth callback flow
+- Constraints:
+  - Must use passport.js (project convention)
+  - Must register in src/auth/index.ts provider registry
+
+Next Action: planning — plan the new OAuth provider implementation following the existing pattern.
+```
+
+## Example 2
+
+User request:
+
+```text
+What caching do we use? I need to cache API responses.
+```
+
+Expected result:
+
+- search for caching patterns in the codebase
+- identify existing cache implementations
+- note configuration and conventions
+
+Sample completed output:
+
+```
+Goal/Result: Researched caching patterns. Found Redis-based caching in use for sessions but no API response caching.
+
+Key Details:
+- Existing implementations:
+  - src/cache/redis.ts — Redis client wrapper (ioredis)
+  - src/middleware/session.ts — Uses Redis for session storage
+  - No API response caching found anywhere
+- Patterns found:
+  - Redis connection config in src/config/redis.ts
+  - TTL conventions: sessions use 24h, no other TTL patterns
+  - Cache keys use prefix pattern: "app:{type}:{id}"
+- Gaps:
+  - No response caching middleware exists
+  - No cache invalidation strategy documented
+- Constraints:
+  - Redis is already a dependency — reuse existing connection
+  - Key prefix pattern must be followed
+
+Next Action: planning — design a response caching middleware using the existing Redis setup.
+```

package/skills/research/meta.yaml

@@ -0,0 +1,27 @@
+name: research
+version: 0.1.0
+category: discovery
+summary: Understand existing code, patterns, and decisions before writing new code to avoid reinventing what exists.
+summary_vi: "T\xECm hi\u1EC3u code, pattern, v\xE0 quy\u1EBFt \u0111\u1ECBnh hi\u1EC7n c\xF3 tr\u01B0\u1EDBc khi vi\u1EBFt code m\u1EDBi \u0111\u1EC3 tr\xE1nh l\xE0m l\u1EA1i nh\u1EEFng g\xEC \u0111\xE3 c\xF3."
+triggers:
+  - research this codebase
+  - what do we already have for X
+  - look into how this works
+  - explore before implementing
+inputs:
+  - topic or feature to research
+  - optional file paths or package names
+outputs:
+  - existing implementations found
+  - patterns and conventions discovered
+  - gaps identified
+  - actionable recommendations
+constraints:
+  - search before assuming nothing exists
+  - read actual code not just filenames
+related_skills:
+  - using-skills
+  - planning
+  - brainstorming
+  - extract
+  - repo-onboarding

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

@@ -0,0 +1,23 @@
+## Goal/Result
+
+- What was researched:
+- Key conclusion:
+
+## Key Details
+
+### Existing Implementations
+- `path/to/file`: Does X
+
+### Patterns Found
+- Pattern 1: Used for...
+
+### Gaps Identified
+- What is missing:
+
+### Constraints Discovered
+- Convention 1:
+- Architecture constraint 1:
+
+## Next Action
+
+- Recommended follow-up: