@pixelcraft-tw/spec 1.0.0

package/templates/architectures/mvvm/kotlin-android.md

@@ -0,0 +1,79 @@
+# Architecture: MVVM (Android / Kotlin)
+
+## Pattern Overview
+Android app organized into model, ui, viewmodel, and data packages. ViewModels extend `ViewModel()` and expose `StateFlow` to Jetpack Compose screens.
+
+## Directory Structure
+```
+app/src/main/java/com/example/app/
+├── model/
+│   ├── Order.kt
+│   └── User.kt
+├── ui/
+│   ├── order/
+│   │   ├── OrderListScreen.kt
+│   │   └── OrderDetailScreen.kt
+│   ├── components/
+│   │   └── OrderCard.kt
+│   ├── navigation/AppNavigation.kt
+│   └── theme/Theme.kt
+├── viewmodel/
+│   ├── OrderListViewModel.kt
+│   └── OrderDetailViewModel.kt
+├── data/
+│   ├── repository/
+│   │   ├── OrderRepository.kt              # interface
+│   │   └── OrderRepositoryImpl.kt
+│   ├── remote/
+│   │   ├── api/OrderApi.kt                 # Retrofit interface
+│   │   └── dto/OrderDto.kt
+│   └── local/
+│       ├── dao/OrderDao.kt                  # Room DAO
+│       └── entity/OrderEntity.kt
+├── di/
+│   ├── AppModule.kt
+│   ├── NetworkModule.kt
+│   └── DatabaseModule.kt
+└── App.kt                                   # Application class
+app/src/test/                                 # Unit tests
+app/src/androidTest/                          # Instrumented tests
+```
+
+## Responsibility Split
+- model → plain Kotlin data classes, no Android dependency
+- ui → Compose screens and components, observe ViewModel StateFlow, send user actions to ViewModel
+- viewmodel → extend `ViewModel()`, hold UI state as `StateFlow`, call Repositories
+- data/repository → data access abstraction; interface in repository/, impl calls remote + local
+- data/remote → Retrofit API interfaces and DTOs
+- data/local → Room DAOs and entities
+- di → Hilt modules wiring everything together
+
+## Recommended Dependencies
+- DI: Hilt
+- Networking: Retrofit + OkHttp
+- Local Storage: Room
+- Navigation: Navigation Compose
+- Async: Kotlin Coroutines + Flow
+- State: StateFlow + Compose collectAsStateWithLifecycle
+
+## Conventions
+- One ViewModel per screen
+- ViewModel exposes `StateFlow<UiState>` via `MutableStateFlow` + `asStateFlow()`
+- Screens collect state with `collectAsStateWithLifecycle()`
+- Repository interface in data/repository/, implementation calls remote + local sources
+- Hilt @Module classes in di/ package
+
+## File Naming
+- PascalCase: OrderListViewModel.kt
+- Screen: *Screen.kt
+- ViewModel: *ViewModel.kt
+- Repository interface: *Repository.kt
+- Repository impl: *RepositoryImpl.kt
+- DAO: *Dao.kt
+- API: *Api.kt
+
+## Testing
+- model: pure unit tests, JUnit
+- viewmodel: unit tests with mocked repositories, Turbine for Flow testing
+- data: integration tests with Room in-memory DB
+- ui: Compose UI tests with composeTestRule

package/templates/architectures/mvvm/swift-ios.md

@@ -0,0 +1,66 @@
+# Architecture: MVVM (iOS / SwiftUI)
+
+## Pattern Overview
+iOS app organized into Models, Views, ViewModels, and Services under `Sources/`. ViewModels use @Observable macro to drive SwiftUI views via data binding.
+
+## Directory Structure
+```
+Sources/
+├── Models/
+│   ├── Order.swift
+│   └── User.swift
+├── Views/
+│   ├── OrderListView.swift
+│   ├── OrderDetailView.swift
+│   └── Components/
+│       └── OrderCard.swift
+├── ViewModels/
+│   ├── OrderListViewModel.swift
+│   └── OrderDetailViewModel.swift
+├── Services/
+│   ├── OrderService.swift
+│   └── AuthService.swift
+├── Repositories/
+│   ├── OrderRepository.swift
+│   └── UserRepository.swift
+└── App.swift
+Tests/
+├── ModelsTests/
+├── ViewModelsTests/
+├── ServicesTests/
+└── RepositoriesTests/
+```
+
+## Responsibility Split
+- Models → plain Swift structs/enums, Codable
+- Views → SwiftUI views, observe ViewModel properties, send user actions to ViewModel
+- ViewModels → @Observable classes, hold UI state, call Services/Repositories
+- Services → network requests (URLSession), external integrations
+- Repositories → data access abstraction over local + remote sources
+
+## Recommended Dependencies
+- State Management: @Observable (Observation framework, built-in)
+- Networking: URLSession (built-in)
+- Navigation: NavigationStack (SwiftUI native)
+- Local Storage: SwiftData
+- DI: Factory pattern or manual injection via init
+
+## Conventions
+- One ViewModel per screen or major UI section
+- ViewModel is an @Observable class; Views observe it directly
+- Views never import Services or Repositories
+- Models are value types (structs) where possible
+
+## File Naming
+- PascalCase: OrderListViewModel.swift
+- View: *View.swift
+- ViewModel: *ViewModel.swift
+- Service: *Service.swift
+- Repository: *Repository.swift
+- Model: descriptive name under Models/
+
+## Testing
+- Models: pure unit tests, XCTest
+- ViewModels: unit tests with mocked services/repositories
+- Services: integration tests or URLProtocol mocking
+- Views: ViewInspector or snapshot tests

package/templates/claude-commands/sf.clarify.md

@@ -0,0 +1,18 @@
+---
+description: Run requirement clarification on a spec
+---
+
+Parse $ARGUMENTS:
+- First word not starting with @ or / is <name>
+- @ prefixed = agent, / prefixed = skill
+- Remaining = supplementary instructions
+
+Read `.workflow/specs/<name>.md`.
+
+Analyze spec, identify requirements that can be further clarified.
+Present as numbered questions, wait for user answers.
+Update spec based on answers.
+
+{If @agent present, involve corresponding agent}
+{If /skill present, use corresponding MCP/skill to assist}
+{Supplementary instructions}

package/templates/claude-commands/sf.implement.md

@@ -0,0 +1,80 @@
+---
+description: Implement code task by task
+---
+
+Parse $ARGUMENTS:
+- First word not starting with @, /, or -- is <name>
+- --backend claude|codex
+- --test [tdd] [intg]: test strategy
+- @ prefixed = agent, / prefixed = skill
+- Remaining = supplementary instructions
+
+Read `.workflow/state.yaml` to confirm current status.
+Read `.workflow/plans/<name>.md` to get task list.
+
+## Pre-flight
+If first run (phase = ready_to_implement):
+1. Create new branch: `git checkout -b <type>/<name>` (branch name MUST be English)
+2. Update state.yaml phase to implementing
+
+## Execution Loop
+For the next pending task:
+
+1. Read the task spec
+2. First scan codebase to understand relevant existing modules, design patterns, utility functions
+3. Prioritize reusing existing code; implement with minimal changes (don't over-engineer)
+4. Follow git commit convention (refer to CLAUDE.md; default is conventional commits)
+5. On completion: `git add -A && git commit -m "<type>(<name>): task-N <title>"` (commit message MUST be English, no Co-Authored-By trailer)
+
+### Testing (based on --test parameter)
+- `--test tdd`: TDD mode
+  - Write failing tests first → confirm FAIL
+  - Write minimum code → confirm PASS
+  - Refactor → confirm still PASS
+  - `git add -A && git commit -m "test(<name>): task-N <title>"`
+- `--test tdd intg`: TDD + integration tests
+  - Same as above, but tests include integration tests
+- `--test intg`: Post-hoc integration tests
+  - Generate integration tests after implementation
+  - `git add -A && git commit -m "test(<name>): task-N <title>"`
+- `--test` (no value): Post-hoc unit tests
+  - Generate unit tests after implementation
+  - `git add -A && git commit -m "test(<name>): task-N <title>"`
+- No --test: don't generate tests
+
+### AI Review
+1. Extract git diff for this task
+2. Review against task spec
+3. Label issues by severity (Critical / Warning / Info)
+4. Save review to `.workflow/reviews/<name>-task-N.md`
+
+### Present to User
+- Changed file list
+- AI review summary
+- Condensed diff
+- Options: [approve] [request-change] [add-test] [skip]
+
+### Handle User Choice
+- approve: update state.yaml, task status = complete
+- request-change: read feedback, reset commits, re-implement
+- add-test: generate tests, commit, re-review
+- skip: update state.yaml, task status = skipped
+
+### All Tasks Complete
+Present task summary.
+
+#### Final Code Review
+Before presenting merge options (skip if `--skip-review` was passed):
+1. Get full branch diff: `git diff $(git merge-base <base-branch> HEAD)..HEAD` (base branch from state.yaml `base_branch` field, fallback to `main`)
+2. Read spec and plan files
+3. Perform **comprehensive code review** of all changes — read and analyze actual code, not just diff stats
+4. If @agents or /skills were specified, involve them in the review
+5. If no agents/skills specified, proactively use available review tools (e.g., /simplify, /code-review, code-reviewer agent)
+6. Save review to `.workflow/reviews/<name>-final.md`
+7. Present review findings to user with severity labels (Critical/Warning/Info) and verdict (PASS/NEEDS_CHANGES)
+
+Options: [merge] [squash-merge] [keep-branch]
+
+{@agent instructions}
+{/skill instructions}
+{Supplementary instructions}

package/templates/claude-commands/sf.new.md

@@ -0,0 +1,22 @@
+---
+description: Create a new spec file
+---
+
+Create a spec based on user input.
+
+Parse $ARGUMENTS:
+- First word is the feature name <name> (MUST be English, kebab-case. If user provides Chinese, translate to English)
+- If `--jira <tickets...>` present, read each ticket's content via Jira MCP (supports multiple, space-separated)
+- If `--desc` present, following text is the description
+- If `-i` present, enter interactive Q&A
+- Remaining text is treated as feature description
+
+Steps:
+1. Check if `.workflow/specs/<name>.md` already exists; if so, ask to confirm overwrite
+2. Generate spec based on input method:
+   - No extra args: copy `.workflow/templates/spec-template.md` to `.workflow/specs/<name>.md`
+   - Has description text: expand into complete spec
+   - Has --jira: read Jira content and convert to spec
+   - Has -i: ask questions step by step to generate spec
+3. Display generated spec content
+4. Prompt user they can manually edit then run `/pxs:refine <name>`

package/templates/claude-commands/sf.refine.md

@@ -0,0 +1,47 @@
+---
+description: Refine spec and decompose implementation plan
+---
+
+Parse $ARGUMENTS:
+- First word not starting with @ or / is <name>
+- @ prefixed words are agent references
+- / prefixed words are skill/MCP references
+- --skip-clarify skips requirement clarification
+- Remaining text is supplementary instructions
+
+Read `.workflow/specs/<name>.md`.
+
+## Phase 1: Requirement Clarification
+Unless --skip-clarify is present:
+1. Analyze spec, identify ambiguous or incomplete requirements
+2. Present as numbered questions with suggested options
+3. Wait for user answers
+4. Follow up if needed (max 3 rounds)
+5. If spec is sufficiently clear, inform user and proceed to next phase
+
+{If @agent present, involve corresponding agent in requirement analysis}
+{If /skill present, use corresponding MCP/skill to assist analysis}
+
+## Phase 2: Refine Spec
+1. First scan codebase to understand existing architecture, modules, design patterns, infrastructure
+2. Refine spec based on confirmed requirements and codebase analysis
+3. Prioritize reusing existing modules; design for minimal change
+4. Add technical details, architecture decisions (with rationale and alternatives), API design, file paths, acceptance criteria
+5. Each architecture suggestion includes justification (why needed, existing alternatives, cost of introduction)
+6. Overwrite `.workflow/specs/<name>.md`
+7. Present refined spec to user for confirmation
+8. User approves to continue; otherwise modify based on feedback
+
+## Phase 3: Decompose Plan
+1. Determine feature type (feat/fix/refactor/docs/chore)
+2. Decompose requirements into independently completable tasks
+3. Each task lists: title, affected files, description, dependencies, complexity, acceptance criteria
+4. Generate `.workflow/plans/<name>.md`
+5. Present plan to user:
+   - Type and branch naming
+   - Each task's content
+6. User approve → update `.workflow/state.yaml`
+7. User edit → wait for modifications
+8. User re-split → re-decompose based on feedback
+
+{Supplementary instructions: $REMAINING_TEXT}

package/templates/claude-commands/sf.review.md

@@ -0,0 +1,17 @@
+---
+description: View review records
+---
+
+Parse $ARGUMENTS:
+- First word not starting with @, /, or -- is <name>
+- --step N: view specific task review
+- --summary: all tasks summary
+- @ prefixed = agent, / prefixed = skill
+
+Read `.workflow/state.yaml`.
+
+- No options: show current pending review or most recent review
+- --step N: read `.workflow/reviews/<name>-task-N.md` and display
+- --summary: list all tasks' review status
+
+{If @agent /skill present, they can provide supplementary analysis on existing reviews}

package/templates/claude-commands/sf.status.md

@@ -0,0 +1,12 @@
+---
+description: View workflow status
+---
+
+Parse $ARGUMENTS:
+- Has value → show specific feature status
+- No value → list all features
+
+Read `.workflow/state.yaml`.
+
+- No args: list all features with name, type, phase, task progress, branch
+- Has <name>: show detailed status for that feature, including each task's status

package/templates/workflow/config.yaml

@@ -0,0 +1,17 @@
+# .workflow/config.yaml
+project:
+  name: ""
+  language: ""
+  framework: ""
+  architecture: none
+  lang_framework: ""
+
+git:
+  convention: conventional
+
+backend:
+  default: claude
+
+test:
+  strategy: none
+  type: unit

package/templates/workflow/prompts/clarify.md

@@ -0,0 +1,39 @@
+You are a senior developer with architect-level vision. Read the following spec and first analyze the project's existing codebase.
+
+## Spec Content
+{spec_content}
+
+## Step 1: Codebase Analysis
+Before asking questions, scan the project:
+1. Understand existing directory structure, module organization, layered architecture
+2. Identify existing shared modules, utility functions, middleware, design patterns
+3. Confirm third-party packages and infrastructure already in use (caching, MQ, ORM, etc.)
+4. Review CLAUDE.md / AGENTS.md / README for project conventions
+
+## Step 2: Requirements Analysis
+Based on codebase analysis, identify:
+1. Ambiguous or incomplete requirements
+2. Potential edge cases
+3. Missing technical decisions (database, API design, error handling, etc.)
+4. Potential conflicts or contradictions
+5. Integration points with existing architecture and possible conflicts
+
+## Step 3: Architecture-Level Confirmation
+If requirements may involve architectural changes, proactively confirm:
+- Whether existing modules can be reused (codebase already has similar functionality)
+- Whether shared modules need to be extracted (repeated logic in multiple places)
+- Whether design patterns need to be introduced (first state which patterns the codebase already uses, suggest consistency)
+- Whether new infrastructure is needed (caching, message queues, etc.) — only suggest when existing solutions genuinely cannot satisfy the need
+
+## Core Principles
+<HARD-GATE>
+- Minimal change first: if existing code can handle it, don't create new code
+- Reuse first: look for what the codebase already has before considering new additions
+- Simple solution first: don't over-engineer for architectural correctness
+- Every architecture suggestion must include: why it's needed, existing alternatives, cost of introduction
+- If the user's requirement can be solved with a simple implementation, don't proactively suggest complex solutions
+</HARD-GATE>
+
+Present questions in numbered format with suggested options.
+For architecture suggestions, explain why it's needed, whether alternatives exist in the codebase, and the cost of introduction.
+If the spec is sufficiently clear and no architectural changes are needed, reply with "Requirements are clear, ready to proceed to refinement phase."

package/templates/workflow/prompts/final-review.md

@@ -0,0 +1,30 @@
+You are a senior code reviewer. Perform a comprehensive review of the entire feature branch.
+
+## Full Diff
+{branch_diff}
+
+## Feature Spec
+{spec_content}
+
+## Implementation Plan
+{plan_content}
+
+## Review Items
+1. Completeness — do changes fully implement the spec?
+2. Correctness — is the logic correct across all tasks?
+3. Cohesion — do tasks work together consistently?
+4. Minimal Change — no unnecessary changes?
+5. Architecture Consistency — follows existing patterns?
+6. Error Handling — missing error scenarios?
+7. Security — any concerns?
+8. Performance — obvious issues?
+9. Code Quality — readability, naming, structure
+
+Label each issue: Critical | Warning | Info
+Final verdict: PASS / NEEDS_CHANGES
+
+## IMPORTANT: Review Depth
+You MUST read and analyze the actual code changes — not just summarize file names or diff stats.
+For each significant change, review the implementation logic, check for edge cases, and verify against the spec.
+If @agents or /skills are specified above, use them. Otherwise, perform the review yourself with full rigor.
+If you have access to review-related tools (e.g., /simplify, /code-review, code-reviewer agent), use them proactively.

package/templates/workflow/prompts/implement-tdd.md

@@ -0,0 +1,35 @@
+You are a senior developer with architect-level vision, strictly following TDD (Test-Driven Development).
+
+## Pre-Implementation: Codebase Scan
+Before writing any tests, scan the codebase to understand:
+1. Existing test framework and test style
+2. Existing test helpers, fixtures, mocks
+3. Reusable test utilities and setup functions
+4. Project's test directory structure conventions
+
+Write tests following the existing test style; don't introduce new test frameworks or patterns.
+
+## Task Spec
+{task_content}
+
+## TDD Flow (strictly follow, no skipping)
+
+### RED: Write Failing Tests
+1. Write tests based on task acceptance criteria
+2. Run tests, confirm all FAIL
+3. If any test PASSes, the test is wrong — rewrite
+
+### GREEN: Write Minimum Code
+1. Write the minimum code to make all tests PASS
+2. Don't write beyond what tests require
+3. Run tests, confirm all PASS
+
+### REFACTOR: Refactor
+1. Refactor while all tests PASS
+2. Run tests after each refactoring to confirm still PASS
+
+<HARD-GATE>
+- NEVER write implementation code before writing tests
+- If you find yourself writing implementation first, delete it and start over
+- Report status after each phase (RED/GREEN/REFACTOR)
+</HARD-GATE>

package/templates/workflow/prompts/implement.md

@@ -0,0 +1,43 @@
+You are a senior developer with architect-level vision. Implement code based on the following task spec.
+
+## Task Spec
+{task_content}
+
+## Previous Task Change Summary
+{previous_diff}
+
+## Pre-Implementation: Codebase Scan (required for every task)
+Before writing any code:
+1. Check what files, classes, and functions already exist in relevant directories
+2. Identify existing code that can be directly reused or extended
+3. Confirm the project's naming conventions, error handling patterns, and logging style
+4. If the task involves a new module, confirm placement aligns with existing directory structure
+
+## Implementation Principles
+
+<HARD-GATE>
+### Minimal Change Principle
+- Prefer using existing utilities, helpers, and base classes from the codebase
+- If similar functionality exists, extend it rather than creating new
+- Don't introduce packages the codebase doesn't currently use, unless the task explicitly requires it
+- Don't refactor outside the task spec scope, even if improvements are visible (note them but don't change)
+- New code must be consistent with surrounding code style (naming, structure, error handling)
+
+### Architecture Consistency
+- Use design patterns already present in the codebase; don't introduce new ones
+- If the codebase uses Repository Pattern, new features should also use Repository Pattern
+- If the codebase uses a specific error handling approach, stay consistent
+- If the codebase has shared types/interfaces, prefer using them
+
+### Record but Don't Execute
+- If you discover an architectural adjustment needed but outside task scope, record in commit message or review notes
+- Format: "Discovery: [describe issue], recommend addressing in a subsequent task"
+</HARD-GATE>
+
+## Git Commit Convention
+- Follow the project's git commit convention (refer to CLAUDE.md / AGENTS.md)
+- If no custom convention is defined, use conventional commits:
+  feat: new feature | fix: bug fix | docs: documentation | style: formatting
+  refactor: refactoring | test: tests | chore: maintenance
+- Commit messages MUST be fully in English (including scope and description)
+- Do NOT add Co-Authored-By trailers

package/templates/workflow/prompts/refine.md

@@ -0,0 +1,52 @@
+You are a senior developer with architect-level vision. Refine the spec based on confirmed requirements and codebase analysis.
+
+## Spec Content
+{spec_content}
+
+## Step 1: Codebase Architecture Inventory
+Before refining the spec, analyze the existing codebase:
+1. Scan directory structure, understand layering and module organization
+2. Identify reusable modules (shared utils, middleware, base classes, interfaces)
+3. Identify design patterns already in use (Repository, Strategy, Event-Driven, etc.)
+4. Inventory existing infrastructure (caching, message queues, schedulers, notification services, etc.)
+5. Review CLAUDE.md / AGENTS.md / README for project conventions and architecture decision records
+
+## Step 2: Technical Solution Design
+Based on codebase analysis, design the implementation approach:
+
+### Architecture Decisions (each must include these three points)
+- **Decision**: What to do (e.g., use existing NotificationService instead of creating new one)
+- **Rationale**: Why (e.g., codebase already has complete Telegram notification implementation)
+- **Alternatives**: What other options exist (e.g., could call Telegram API directly, but would duplicate code)
+
+### Reuse Analysis
+- List existing modules that can be directly reused
+- List existing modules that need minor extensions (explain what changes and why)
+- List modules that must be newly created (explain why existing ones are insufficient)
+
+### Architecture Adjustment Suggestions (only when necessary)
+If requirements genuinely need new patterns or infrastructure:
+- Explain why existing architecture cannot satisfy the need
+- Impact assessment (how many files change, which modules are affected)
+- Minimum viable approach (don't introduce a complete solution at once, satisfy current requirements first)
+
+<HARD-GATE>
+- Minimal change principle: if 3 lines can solve it, don't write 30
+- Reuse first: use what the codebase has, don't reinvent
+- Don't over-design for future requirements: only solve what the spec explicitly asks for
+- Every new dependency (package, service, design pattern) must have clear justification
+- If codebase already uses a pattern (e.g., Repository Pattern), new features must stay consistent
+</HARD-GATE>
+
+## Output Format
+# Feature: <name>
+## Context
+## Codebase Analysis (existing architecture inventory, reusable modules)
+## Requirements (numbered, each with acceptance criteria)
+## Technical Design
+### Architecture Decisions (each with rationale and alternatives)
+### Reuse Plan (which existing modules to reuse, extend, or create new)
+### New Dependencies (if any, with justification)
+## Files (explicit paths with change descriptions, labeled as new/modified/extended)
+## Constraints
+## Acceptance Criteria

package/templates/workflow/prompts/review.md

@@ -0,0 +1,33 @@
+You are a senior code reviewer. Review the following git diff.
+
+## Diff
+```
+{git_diff}
+```
+
+## Original Task Spec
+{task_content}
+
+## Review Items
+1. **Correctness**: Does the code correctly implement the task spec
+2. **Minimal Change**: Were changes minimal in scope; are there unnecessary modifications
+3. **Reusability**: Were existing reusable modules missed; is there unnecessary code duplication
+4. **Architecture Consistency**: Is new code consistent with existing codebase patterns (design patterns, naming, layering)
+5. **Over-engineering**: Was anything implemented outside the spec scope; was unnecessary complexity introduced
+6. **Error Handling**: Are there missing error scenarios
+7. **Security**: Are there security concerns
+8. **Performance**: Are there obvious performance issues
+9. **Code Quality**: Readability, naming, structure
+
+## Output Format
+Label each issue with severity:
+- Critical: must fix to pass
+- Warning: recommended fix
+- Info: for reference only
+
+Final verdict: PASS / NEEDS_CHANGES
+
+## IMPORTANT: Review Depth
+You MUST read and analyze the actual code — not just summarize file names or diff stats.
+For each changed file, review the implementation logic, not just the surface.
+If @agents or /skills are specified above, use them. Otherwise, perform the review yourself with full rigor.

package/templates/workflow/prompts/test.md

@@ -0,0 +1,14 @@
+You are a test engineer. Write {test_type} tests based on the following completed implementation.
+
+## Implementation Diff
+```
+{git_diff}
+```
+
+## Task Spec
+{task_content}
+
+## Rules
+- Tests should cover: happy path, edge cases, error scenarios
+- Use the project's existing test framework and style
+- Don't over-mock; integration tests should use real dependencies where possible

package/templates/workflow/templates/spec-template.md

@@ -0,0 +1,13 @@
+# Feature: <name>
+
+## Context
+<!-- 2-3 sentences of project background -->
+
+## Requirements
+<!-- Numbered list with acceptance criteria -->
+
+## Constraints
+<!-- Technical limitations, compatibility requirements -->
+
+## Notes
+<!-- Additional notes -->