@anionzo/skill 1.3.0 → 1.6.0

package/skills/docs-writer/SKILL.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Keep documentation aligned with how the system actually works.
+Keep documentation aligned with how the system actually works. Support both full document creation and targeted section editing.
 
 ## When To Use
 
@@ -13,22 +13,83 @@ Load this skill when writing or updating:
 - runbooks
 - API usage notes
 - project operating instructions
+- architecture diagrams
+- any documentation that should stay in sync with code
 
 ## Workflow
 
 1. Confirm the target audience and document purpose.
 2. Verify current behavior from source, commands, or config before writing.
-3. Update only the sections that need to change.
-4. Prefer concise instructions, examples, and commands over long prose.
-5. Call out assumptions or areas that still need verification.
+3. Determine scope: full document or section edit.
+4. For section edits, update only the sections that need to change — do not rewrite the entire document.
+5. Prefer concise instructions, examples, and commands over long prose.
+6. Use diagrams (mermaid) for complex flows or architecture.
+7. Call out assumptions or areas that still need verification.
+
+## Section Editing
+
+For targeted updates, prefer editing specific sections rather than rewriting the full document:
+
+1. Identify which section(s) need updating.
+2. Read the current section content.
+3. Update only the affected section while preserving surrounding structure.
+4. Verify the update does not break references or flow.
+
+This is more efficient and less error-prone than full document rewrites.
+
+## Mermaid Diagrams
+
+Use mermaid diagrams for:
+- Architecture diagrams
+- Flowcharts
+- Sequence diagrams
+- Entity relationships
+- Decision trees
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[End]
+```
+````
+
+````markdown
+```mermaid
+sequenceDiagram
+    Client->>Server: Request
+    Server->>DB: Query
+    DB-->>Server: Result
+    Server-->>Client: Response
+```
+````
+
+Diagrams render in GitHub, most doc platforms, and many editor previews. Use them when a text description would be confusing.
 
 ## Output Format
 
-- target document
-- audience
-- what changed
-- source of truth used
-- assumptions or follow-ups
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — what document was created, updated, or inspected
+2. **Key Details:**
+   - target document and audience
+   - what changed (or what was created)
+   - source of truth used for verification
+   - whether section edit or full rewrite
+   - assumptions or follow-ups
+3. **Next Action** — only when a natural follow-up exists:
+   - if doc reveals code issues → `debug`
+   - if doc is part of feature work → `verification-before-completion`
+
+## Documentation Rules
+
+- Verify against actual source before writing.
+- Prefer section edits over full rewrites.
+- Use mermaid for complex flows.
+- Keep instructions concise with examples and commands.
+- Remove stale commands, paths, and references.
+- Do not mix user instructions with internal implementation details unnecessarily.
 
 ## Red Flags
 
@@ -36,7 +97,21 @@ Load this skill when writing or updating:
 - writing broad architecture claims without source verification
 - mixing user instructions with internal implementation details unnecessarily
 - leaving stale commands or paths in place
+- rewriting an entire document when only one section needed updating
+- creating near-duplicate docs instead of updating existing ones
+- leaving broken cross-references after an edit
+
+## Checklist
+
+- [ ] Target audience confirmed
+- [ ] Current behavior verified from source
+- [ ] Scope determined (section edit vs full document)
+- [ ] Content written with concise examples
+- [ ] Mermaid diagrams used where helpful
+- [ ] Stale content removed or corrected
+- [ ] Cross-references checked
+- [ ] Source of truth documented
 
 ## Done Criteria
 
-This skill is complete when the updated document has been verified against the actual source, all stale commands or paths have been corrected or removed, and the "Verification" field in the output names the specific files or commands that were checked.
+This skill is complete when the updated document has been verified against the actual source, all stale commands or paths have been corrected or removed, and the output names the specific files or commands that were checked.

package/skills/docs-writer/meta.yaml

@@ -1,22 +1,26 @@
 name: docs-writer
-version: 0.1.0
+version: 0.2.0
 category: documentation
-summary: Update documentation from verified source behavior so the docs stay useful and current.
-summary_vi: Cập nhật tài liệu từ hành vi nguồn đã xác minh để docs luôn hữu ích và cập nhật.
+summary: Write and update documentation aligned with actual code, with section editing and mermaid diagram support.
+summary_vi: "Vi\u1EBFt v\xE0 c\u1EADp nh\u1EADt t\xE0i li\u1EC7u theo code th\u1EF1c t\u1EBF, h\u1ED7 tr\u1EE3 ch\u1EC9nh s\u1EEDa t\u1EEBng ph\u1EA7n v\xE0 s\u01A1 \u0111\u1ED3 mermaid."
 triggers:
+  - write documentation
   - update the README
-  - write onboarding docs
-  - refresh runbook or API notes
+  - document this feature
+  - create a runbook
 inputs:
-  - current code or behavior
-  - existing documentation
+  - target document
+  - audience
+  - source of truth (code, commands, config)
 outputs:
-  - updated docs
-  - assumptions and verification notes
+  - created or updated document
+  - verification source noted
+  - assumptions or follow-ups
 constraints:
-  - prefer source-verified statements
-  - keep links repository-relative when possible
+  - verify against actual source before writing
+  - prefer section edits over full rewrites
 related_skills:
   - using-skills
   - repo-onboarding
-  - code-review
+  - feature-delivery
+  - verification-before-completion

package/skills/extract/SKILL.md

@@ -0,0 +1,161 @@
+# 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.
+
+## 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"
+
+Skip this skill when work was routine with no surprises or novel patterns.
+
+## Workflow
+
+1. Identify the source of knowledge (completed task, code change, debugging session).
+2. Analyze across three categories: patterns, decisions, and failures.
+3. Check for existing documentation that should be updated (avoid duplicates).
+4. Create or update knowledge documentation.
+5. Promote critical learnings that would save significant time if known in advance.
+
+## 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 (patterns, decisions, failures)
+   - 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
+   - 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
+- 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)
+- [ ] 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 the three-category analysis is done and any findings worth preserving are documented in the appropriate location. If nothing worth extracting 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,27 @@
+name: extract
+version: 0.1.0
+category: knowledge
+summary: Extract reusable patterns, decisions, and failure learnings from completed work to compound knowledge.
+summary_vi: "Tr\xEDch xu\u1EA5t pattern, quy\u1EBFt \u0111\u1ECBnh, v\xE0 b\xE0i h\u1ECDc t\u1EEB c\xF4ng vi\u1EC7c ho\xE0n th\xE0nh \u0111\u1EC3 t\xEDch l\u0169y ki\u1EBFn th\u1EE9c."
+triggers:
+  - extract learnings from this task
+  - document what we learned
+  - capture this pattern
+  - what did we learn
+inputs:
+  - completed task or feature
+  - code changes or debugging session
+outputs:
+  - patterns documented
+  - decisions recorded
+  - failures captured
+  - critical learnings promoted
+constraints:
+  - search existing docs before creating new ones
+  - do not fabricate findings
+  - three-category analysis required
+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`
 
 ## Red Flags
 

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
+  - debug
   - verification-before-completion
   - code-review
+  - docs-writer
+  - go-pipeline
+  - test-driven-development

package/skills/go-pipeline/SKILL.md

@@ -0,0 +1,156 @@
+# Go Pipeline
+
+## Purpose
+
+Execute a full development pipeline from an approved spec: break into tasks, plan each, implement each, verify all, and commit — in one continuous run with minimal review gates.
+
+This skill exists for when the spec is approved and the user wants execution, not incremental review at each step.
+
+## When To Use
+
+Load this skill when:
+
+- the user has an approved spec and wants to execute everything in one shot
+- the user says "run all", "go mode", "execute everything", or "just build it"
+- all requirements are clear and decisions are locked
+
+## When NOT To Use
+
+- Spec is still a draft — redirect to `brainstorming` first.
+- User wants to review each task individually — use `planning` + `feature-delivery` per task.
+- Spec has unresolved open questions — resolve them first.
+- The scope is too large for one context window — use `planning` + `feature-delivery` incrementally.
+
+## Workflow
+
+### Phase 1: Validate Spec
+
+Before starting, verify the spec is ready:
+
+- [ ] Spec exists and is approved
+- [ ] Has acceptance criteria defined
+- [ ] No unresolved blocking questions
+- [ ] Requirements are specific enough to implement
+
+If any check fails, STOP and redirect:
+> "Spec not ready. [specific issue]. Run `brainstorming` first."
+
+### Phase 2: Generate Tasks
+
+Parse the spec and break it into ordered implementation tasks:
+
+- Group related requirements into logical tasks
+- Order by dependency (foundational first, dependent last)
+- Each task should be completable in a single implementation session
+- Map each task to the spec acceptance criteria it fulfills
+
+**Report:** "Created X tasks from spec. Starting implementation..."
+
+### Phase 3: Plan + Implement Each Task
+
+Loop through all tasks in dependency order:
+
+For each task:
+1. **Research context** — check related code, patterns, docs
+2. **Draft plan** — concrete steps, files to change, tests to add
+3. **Implement** — work through plan steps
+4. **Verify** — run tests/lint/build after each task
+5. **Mark complete** — note what was done
+
+**Progress report between tasks:**
+> "Task X/Y done: [title]. Continuing..."
+
+### Phase 4: Full Verification
+
+After all tasks complete:
+
+1. Run the full test suite
+2. Run the build
+3. Run linting
+4. Check acceptance criteria coverage:
+
+```
+Coverage Report
+===============
+Spec: [name]
+Tasks: X/X complete (100%)
+ACs: Y/Z verified
+```
+
+If coverage < 100%, identify and address gaps.
+
+### Phase 5: Commit
+
+Stage all changes and prepare a single conventional commit:
+
+```
+feat(<scope>): implement <spec-name>
+
+- Task 1: <title>
+- Task 2: <title>
+- All ACs verified
+```
+
+**This is the ONE gate in go-pipeline — ask user before committing:**
+
+> Pipeline complete. X tasks done, all verified.
+> Ready to commit. Proceed? (yes / no / edit)
+
+## Context Budget Management
+
+If context exceeds approximately 60% during implementation:
+
+1. Finish the current task
+2. Commit completed work so far
+3. Report progress and remaining tasks
+4. Suggest: "Run `go-pipeline` again to continue remaining tasks."
+
+The skill should detect already-completed tasks and skip them on re-run.
+
+## Error Handling
+
+- **Build/test fails during a task:** Fix the error, re-run tests. If unfixable, mark task as blocked, note why, continue to next task.
+- **Spec has conflicting requirements:** STOP and ask user to clarify.
+- **Task depends on blocked task:** Skip and report at the end.
+
+## Output Format
+
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — what was completed across the full pipeline run
+2. **Key Details:**
+   - total tasks created and completed
+   - any blocked or skipped tasks
+   - acceptance criteria coverage percentage
+   - build/test/lint status
+   - commit proposal
+3. **Next Action:**
+   - if complete → commit confirmation
+   - if interrupted → how to resume
+   - if blocked → what to resolve
+
+## Red Flags
+
+- running on a draft or unapproved spec
+- skipping verification between tasks
+- not checking acceptance criteria before marking tasks done
+- committing without user approval
+- ignoring build/test failures
+- not reporting progress between tasks
+- continuing past context budget limit without checkpointing
+- treating this as a shortcut to skip proper spec work
+
+## Checklist
+
+- [ ] Spec is approved
+- [ ] Spec validated (requirements clear, ACs defined)
+- [ ] Tasks generated with AC mapping
+- [ ] Each task: planned, implemented, verified, completed
+- [ ] Full verification passed (tests, build, lint)
+- [ ] AC coverage reported
+- [ ] User approved commit
+- [ ] Commit created
+
+## Done Criteria
+
+This skill is complete when all tasks from the spec are implemented, verified, and committed with user approval — or when progress is checkpointed and the user is informed how to resume.

package/skills/go-pipeline/examples.md

@@ -0,0 +1,56 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+The user-notifications spec is approved. Just build it all.
+```
+
+Expected result:
+
+- validate the spec
+- generate tasks from requirements
+- plan and implement each task
+- verify all ACs
+- present commit for approval
+
+Sample completed output:
+
+```
+Goal/Result: Pipeline complete — 4 tasks implemented, all ACs verified.
+
+Key Details:
+  Spec: user-notifications (approved)
+
+  Tasks completed: 4/4
+  1. Add notification model and database migration — DONE
+  2. Implement notification service with email + in-app delivery — DONE
+  3. Add user notification preferences API — DONE
+  4. Wire notification triggers into existing user events — DONE
+
+  Tasks blocked: 0
+
+  AC Coverage: 5/5 (100%)
+  - AC-1: Notifications created on user events — VERIFIED
+  - AC-2: Email delivery via SendGrid — VERIFIED
+  - AC-3: In-app notifications visible in UI — VERIFIED
+  - AC-4: User preferences respected — VERIFIED
+  - AC-5: Delivery failures logged — VERIFIED
+
+  Build: PASS
+  Tests: 58/58 PASS (12 new)
+  Lint: PASS
+
+  Commit proposal:
+  feat(notifications): implement user notification system
+
+  - Add notification model with email + in-app channels
+  - Implement notification service with delivery tracking
+  - Add user preferences API for per-channel control
+  - Wire notifications into user registration and order events
+  - All 5 acceptance criteria verified
+
+  Proceed? (yes / no / edit)
+```