Imported from markramm/pyrite (.claude/skills/software-kb/SKILL.md). Install upstream with npx skills add markramm/pyrite --skill software-kb. Copyright stays with the author.

Software KB Skill

Pull-based development workflow for software-type Pyrite knowledge bases. Covers the kanban cycle from backlog to done, using sw_* MCP tools (for agents) and pyrite sw CLI commands (for humans).

Announce at start: "I'm using the software-kb skill."

The Development Loop

  Pull         Context       Claim         Work         Submit       Review
┌────────┐   ┌──────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  ┌──────────┐
│ What's  │──>│ Gather   │──>│ Lock the │──>│ Do the  │──>│ Move to  │──>│ Approve  │
│ next?   │   │ context  │   │ item     │   │ work    │   │ review   │   │ or reject│
└────────┘   └──────────┘  └──────────┘  └─────────┘  └──────────┘  └──────────┘
sw_pull_next  sw_context    sw_claim       (you)        sw_submit     sw_review
              _for_item

Status Flow

proposed → accepted → in_progress → review → done
   ↑          ↑           ↑                    │
   │          │           └── changes_requested─┘
   │          └── in_progress (unclaim)
   └── accepted (demote)

Backward transitions: accepted → proposed, accepted → deferred, in_progress → accepted.

Side exits: proposed → wont_do, proposed → deferred → proposed, done → retired.

MCP Tools Quick Reference

Read tier (safe, no side effects)

Write tier (mutates state)

CLI Equivalents

pyrite sw context-for-item <item-id> -k <kb>  # Full context bundle (ADRs, components, deps, reviews, work logs)
pyrite sw board -k <kb>                # Kanban board
pyrite sw backlog -k <kb>              # List backlog
pyrite sw backlog -k <kb> --status accepted  # Filtered
pyrite sw review-queue -k <kb>         # Review queue
pyrite sw claim <item-id> -k <kb> --assignee <name>
pyrite sw submit <item-id> -k <kb>     # Submit for review
pyrite sw transition <item-id> <status> -k <kb>  # Transition with gate check
pyrite sw check-ready <item-id> -k <kb>        # Check DoR without claiming
pyrite sw refine -k <kb>                       # Scan backlog for DoR gaps
pyrite sw adrs -k <kb>                 # List ADRs
pyrite sw new-adr --title "..." -k <kb>  # Create ADR
pyrite sw components -k <kb>           # Component docs
pyrite sw validations -k <kb>          # Validations
pyrite sw conventions -k <kb>          # Conventions
pyrite sw milestones -k <kb>           # Milestones

Workflow Protocols

Starting Work (Agent)

1. sw_pull_next(kb_name=...)           → get recommendation
2. sw_context_for_item(item_id, kb)    → read linked ADRs, validations, reviews
3. sw_claim(item_id, kb, assignee=...) → lock the item (CAS — fails if already claimed)
   ↳ Read the `gate` field in the response (Definition of Ready)
4. Address gate results:
   - checker failures → fix before proceeding (estimate effort, resolve blockers, decompose XL items)
   - judgment items → self-evaluate and fill gaps (add ## Acceptance Criteria, link to ADR, etc.)
   - If policy is "enforce" and checkers failed, the claim is rejected — fix and retry
5. Do the work
6. sw_submit(item_id, kb)              → move to review

If sw_pull_next returns "reason": "WIP limit reached", finish existing in-progress work first.

If sw_pull_next returns blocked items, check if you can unblock them by completing their dependencies.

Reviewing Work

1. sw_review_queue(kb_name=...)        → see what needs review
2. sw_context_for_item(item_id, kb)    → check prior reviews, linked validations
3. Evaluate the work against Definition of Done
4. sw_review(item_id, kb,
     outcome="approved"|"changes_requested",
     reviewer=...,
     feedback=...)                      → record outcome

• approved → transitions to done (triggers DoD gate evaluation — check gate in response)
• changes_requested → transitions back to in_progress (feedback required)
• Before approving, verify agent_responsibility items: tests passing, clean working tree, KB docs updated
• Prior review feedback is surfaced in sw_context_for_item so rework addresses specific issues
• rework_count in the review queue shows how many times an item has been sent back

Logging Work Sessions

Record session context so the next agent doesn't repeat dead ends:

sw_log(item_id, kb_name, summary,
       decisions="...",       # what you chose and why
       rejected="...",        # what you tried and abandoned
       open_questions="...")   # what's unresolved for next session

The tool creates a work_log entry linked to the backlog item via session_for / has_session. These entries surface automatically in sw_context_for_item.

Log at the end of a work session, especially when:

• You made non-obvious design choices
• You tried an approach that didn't work
• You're handing off unfinished work

Checking the Board

sw_board(kb_name=...)

Returns lanes with item counts and WIP limit status. Use this for situational awareness — where is work piling up?

Quality Gates (DoR / DoD)

sw_claim and sw_transition return a gate field containing quality criteria evaluated at transition boundaries:

• DoR (Definition of Ready) fires at sw_claim / transition to in_progress
• DoD (Definition of Done) fires at transition to done

Criterion types

Policy modes

• warn — gate results are advisory; transition proceeds even if checkers fail
• enforce — checker failures block the transition; fix issues and retry

Judgment and agent_responsibility criteria always pass structurally — they rely on the agent to self-evaluate honestly.

Example gate response

{
  "gate": {
    "gate_type": "dor",
    "policy": "warn",
    "passed": false,
    "criteria": [
      {"name": "has_effort_estimate", "type": "checker", "passed": false, "message": "Missing effort estimate"},
      {"name": "has_acceptance_criteria", "type": "judgment", "passed": true, "message": "Item should have clear acceptance criteria"},
      {"name": "tests_passing", "type": "agent_responsibility", "passed": true, "message": "All tests should pass before starting"}
    ]
  }
}

The self-check loop

claim → read gate → fix checker failures → self-evaluate judgment items → proceed

If policy is enforce and a checker failed, the claim is rejected. Fix the issue (e.g., pyrite update <id> -k <kb> -f effort=M) and retry the claim.

Backlog Refinement

Proactively prepare backlog items so they pass DoR before anyone claims them.

The refinement loop

1. pyrite sw refine -k <kb>              → scan for DoR gaps
2. For each item with gaps, highest priority first:
   a. Auto-fix what you can:
      - Add effort estimate based on scope analysis
      - Link to relevant ADRs/components
      - Add missing tags
      - Decompose XL items into subtasks
   b. Flag what needs human input:
      - Ambiguous requirements → add ## Open Questions to item body
      - Missing acceptance criteria needing product context → note it
      - Architectural questions → suggest creating an ADR
   c. pyrite sw check-ready <id> -k <kb>  → verify fixes
3. Transition ready items: proposed → accepted (if appropriate)
   - ALWAYS provide a descriptive reason that captures WHY the item is ready
   - Format: "Per refinement: <effort>, <risk>, <impact> (<rationale>)"
   - Example: "Per refinement: Small, low risk, high impact (unblocks backward transitions for blocked items)"
   - NEVER use generic reasons like "Ready per refinement" — the reason should help future readers understand the decision

What agents can fix autonomously

• Effort estimates (analyze scope, set S/M/L)
• Missing tags (infer from title/body)
• ADR/component links (search KB for related entries)
• Decomposition (create sub-items for XL work, link with blocked_by)

What needs human input

• Acceptance criteria requiring product/business context
• Priority decisions between competing items
• Architectural choices not covered by existing ADRs
• Scope questions ("should this include X?")

For these, add a ## Open Questions section to the item body with specific asks.

Backlog Item Fields

Priority Semantics

• critical — blocking other work or production issue; pull immediately
• high — important for current milestone; pull before medium
• medium — default; pull in order
• low — nice-to-have; pull when nothing else is available

sw_pull_next ranks by priority then age (oldest first within same priority).

Dependencies

Backlog items can have blocked_by / blocks relationships:

• sw_pull_next skips blocked items automatically
• sw_claim refuses to claim a blocked item
• sw_context_for_item shows dependency status (resolved or not)
• Blocked items appear in sw_pull_next response under blocked_items

To unblock work, complete the blocking item first.

Linking to Context

Backlog items gain value from links to other entries:

sw_context_for_item assembles all of these in one call. Use it before starting work — it's the single source of truth for what an item needs.

Anti-patterns