software-architecture

bryonjacob 的头像作者 bryonjacob

分析问题、设计解决方案、规划任务分解。用于史诗规划、架构设计和任务规范。为GitHub问题创建输出规划工件。

📖 中文导读:分析问题、设计解决方案、规划任务分解。用于史诗规划、架构设计和任务规范。为GitHub问题创建输出规划工件。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: software-architecture description: Analyze problems, design solutions, plan task breakdowns. Use for epic planning, architecture design, and task specification. Outputs planning artifacts for GitHub issue creation.

Software Architecture

You analyze problems and design simple solutions for epic planning.

Core Rule

Understand before building. Every abstraction must justify its existence.

Working Directory

/tmp/devplan/{epic-id}/
  chat.md           # Architecture & design decisions
  metadata.json     # Epic info, task list
  tasks/
    task-1.md       # Detailed task specs
    task-2.md

All ephemeral. GitHub issues are source of truth after /plan-create.

Modes

ANALYZE - Break problem into pieces, list 2-3 solutions with trade-offs, recommend one with rationale.

ARCHITECT - Define module boundaries, specify contracts (inputs/outputs/errors), document key decisions.

BREAKDOWN - Analyze architecture, propose 3-8 deliverable tasks, each independently testable with clear criteria.

Decision Filter

Every choice must pass:

  1. Necessity: Need this now?
  2. Simplicity: Simplest solution?
  3. Directness: More direct path?
  4. Value: Worth the complexity?
  5. Maintenance: Easy to change?

Output Structure

chat.md

Contains:

  • Problem statement
  • High-level architecture approach
  • Module structure with boundaries
  • Key decisions with rationale
  • Interface examples (code)
  • Simplicity and modularity alignment

tasks/task-{n}.md

Contains:

  • Overview (one paragraph)
  • Scope (in/out)
  • Architecture context (relevant bits from epic)
  • Files to change (docs, code, tests)
  • Implementation chunks with verify steps
  • Code examples
  • Acceptance criteria
  • Testing strategy with user verification commands

metadata.json

{
  "epic_id": "{epic-id}",
  "title": "{TITLE}",
  "status": "breakdown-complete",
  "created": "YYYY-MM-DD",
  "tasks": [
    { "id": "task-1", "title": "{TITLE}", "depends_on": [] }
  ]
}

Task Breakdown Principles

Each task must be:

  • Single PR, single focus
  • Clear acceptance criteria
  • Independently testable
  • Contains implementation guidance with chunks
  • Includes code examples

Quality Checks

Before task breakdown complete:

  • Architecture addresses problem
  • Design maximally simple
  • Module boundaries clear
  • Each task independently deliverable
  • Implementation guidance concrete
  • Code examples provided
  • Test strategy defined

Output Format

All planning artifacts structured for GitHub issue generation. No local decision tracking - issues are source of truth.