@pixel613/spec 1.0.1

package/templates/architectures/hexagonal/python-fastapi.md

@@ -0,0 +1,43 @@
+# Architecture: Hexagonal / Ports & Adapters (Python + FastAPI)
+
+## Directory Structure
+```
+src/
+├── core/
+│   ├── domain/
+│   │   ├── entities/order.py
+│   │   └── errors.py
+│   └── ports/
+│       ├── inbound/create_order_port.py   # ABC interfaces
+│       └── outbound/order_repository.py   # ABC interfaces
+├── application/
+│   └── services/order_service.py          # Implements inbound ports
+├── adapters/
+│   ├── inbound/
+│   │   └── http/
+│   │       ├── order_router.py
+│   │       └── dependencies.py
+│   └── outbound/
+│       ├── persistence/order_repository.py
+│       └── messaging/event_publisher.py
+└── main.py
+```
+
+## Dependency Rule
+- core → depends on nothing, pure Python ABCs and dataclasses
+- application → implements inbound ports, depends only on core
+- adapters → implement outbound ports or call inbound ports
+
+## Conventions
+- Ports defined as Abstract Base Classes in core/ports/
+- FastAPI dependency injection wires adapters to ports
+- Pydantic for DTOs at adapter boundary
+
+## File Naming
+- snake_case: order_service.py
+- Test files: test_order_service.py
+
+## Testing
+- core: pure unit tests (pytest)
+- application: mock outbound ports
+- adapters: integration tests per adapter

package/templates/architectures/hexagonal/typescript-nestjs.md

@@ -0,0 +1,44 @@
+# Architecture: Hexagonal / Ports & Adapters (NestJS)
+
+## Directory Structure
+```
+src/
+├── core/
+│   ├── domain/
+│   │   ├── entities/order.entity.ts
+│   │   └── value-objects/money.vo.ts
+│   └── ports/
+│       ├── inbound/create-order.port.ts    # Driving ports (use case interfaces)
+│       └── outbound/order.repository.port.ts # Driven ports
+├── application/
+│   └── services/order.service.ts           # Implements inbound ports
+├── adapters/
+│   ├── inbound/
+│   │   ├── http/order.controller.ts        # REST adapter
+│   │   └── grpc/order.grpc.ts              # gRPC adapter
+│   └── outbound/
+│       ├── persistence/order.repository.ts # DB adapter
+│       └── messaging/event.publisher.ts    # Message queue adapter
+└── app.module.ts
+```
+
+## Dependency Rule
+- core (domain + ports) → depends on nothing, defines all interfaces
+- application → implements inbound ports, depends on core only
+- adapters → implement outbound ports or call inbound ports
+
+## Conventions
+- Inbound ports = use case interfaces (what the app can do)
+- Outbound ports = infrastructure interfaces (what the app needs)
+- Adapters are interchangeable (swap DB, swap transport)
+- NestJS modules wire adapters to ports via DI
+
+## File Naming
+- kebab-case: create-order.port.ts
+- Port: *.port.ts
+- Adapter suffix indicates type: *.controller.ts, *.repository.ts
+
+## Testing
+- core: pure unit tests
+- application: mock outbound ports
+- adapters: integration tests per adapter

package/templates/architectures/layered/csharp-aspnet.md

@@ -0,0 +1,45 @@
+# Architecture: Layered / Three-Tier (C# + ASP.NET Core)
+
+## Project Structure
+```
+src/
+├── Controllers/
+│   ├── OrderController.cs
+│   └── AuthController.cs
+├── Services/
+│   ├── IOrderService.cs
+│   ├── OrderService.cs
+│   └── IAuthService.cs
+├── Repositories/
+│   ├── IOrderRepository.cs
+│   ├── OrderRepository.cs
+│   └── ApplicationDbContext.cs
+├── Models/
+│   ├── Order.cs
+│   └── User.cs
+├── DTOs/
+│   ├── CreateOrderDto.cs
+│   └── LoginDto.cs
+├── Middleware/
+│   └── ExceptionHandlerMiddleware.cs
+└── Program.cs
+```
+
+## Layer Dependencies
+- Controllers → Services → Repositories → Database
+- Each layer only depends on the layer directly below
+
+## Conventions
+- Interface-based DI for Services and Repositories
+- EF Core for data access
+- DTOs at controller boundary
+- Middleware for cross-cutting concerns
+
+## File Naming
+- PascalCase: OrderService.cs
+- Interface prefix: IOrderService.cs
+
+## Testing
+- Services: unit tests (xUnit + NSubstitute)
+- Controllers: unit tests with mocked services
+- Repositories: integration tests (WebApplicationFactory)

package/templates/architectures/layered/go-gin.md

@@ -0,0 +1,41 @@
+# Architecture: Layered / Three-Tier (Go + Gin)
+
+## Directory Structure
+```
+internal/
+├── handler/
+│   ├── order_handler.go
+│   ├── auth_handler.go
+│   ├── middleware/
+│   └── router.go
+├── service/
+│   ├── order_service.go
+│   └── auth_service.go
+├── repository/
+│   ├── order_repo.go
+│   └── user_repo.go
+├── model/
+│   ├── order.go
+│   └── user.go
+└── config/
+    └── env.go
+```
+
+## Layer Dependencies
+- Handler → Service → Repository → Database
+- Each layer only depends on the layer directly below
+
+## Conventions
+- Handlers handle HTTP concerns (Gin context)
+- Services contain business logic, accept/return domain models
+- Repositories handle data access
+- Interfaces defined at consumer side for testability
+
+## File Naming
+- snake_case: order_service.go
+- Test files: order_service_test.go
+
+## Testing
+- services: unit tests with mocked repositories
+- handlers: HTTP tests (httptest)
+- repositories: integration tests

package/templates/architectures/layered/python-fastapi.md

@@ -0,0 +1,42 @@
+# Architecture: Layered / Three-Tier (Python + FastAPI)
+
+## Directory Structure
+```
+src/
+├── routers/
+│   ├── order_router.py
+│   └── auth_router.py
+├── services/
+│   ├── order_service.py
+│   └── auth_service.py
+├── repositories/
+│   ├── order_repository.py
+│   └── user_repository.py
+├── models/
+│   ├── order.py
+│   └── user.py
+├── schemas/
+│   ├── order_schema.py           # Pydantic models
+│   └── auth_schema.py
+├── config.py
+└── main.py
+```
+
+## Layer Dependencies
+- Routers → Services → Repositories → Database
+- Each layer only depends on the layer directly below
+
+## Conventions
+- FastAPI dependency injection for wiring
+- Pydantic schemas at router boundary
+- Services contain business logic
+- Repositories handle SQLAlchemy queries
+
+## File Naming
+- snake_case: order_service.py
+- Test files: test_order_service.py
+
+## Testing
+- services: unit tests (pytest + mock)
+- routers: HTTP tests (TestClient)
+- repositories: integration tests

package/templates/architectures/layered/typescript-nestjs.md

@@ -0,0 +1,48 @@
+# Architecture: Layered / Three-Tier (NestJS)
+
+## Directory Structure
+```
+src/
+├── controllers/
+│   ├── order.controller.ts
+│   └── auth.controller.ts
+├── services/
+│   ├── order.service.ts
+│   └── auth.service.ts
+├── repositories/
+│   ├── order.repository.ts
+│   └── user.repository.ts
+├── entities/
+│   ├── order.entity.ts
+│   └── user.entity.ts
+├── dtos/
+│   ├── create-order.dto.ts
+│   └── login.dto.ts
+├── guards/
+├── interceptors/
+├── pipes/
+└── app.module.ts
+```
+
+## Layer Dependencies
+- Controllers → Services → Repositories → Database
+- Each layer only depends on the layer directly below
+
+## Conventions
+- Controllers handle HTTP, validate input via DTOs + Pipes
+- Services contain business logic
+- Repositories handle data access (TypeORM/Prisma/MikroORM)
+- NestJS DI wires everything together
+
+## File Naming
+- kebab-case: order.service.ts, create-order.dto.ts
+- Controller: *.controller.ts
+- Service: *.service.ts
+- Repository: *.repository.ts
+- Entity: *.entity.ts
+
+## Testing
+- services: unit tests with mocked repositories
+- controllers: unit tests with mocked services
+- repositories: integration tests
+- E2E: supertest

package/templates/architectures/modular/csharp-aspnet.md

@@ -0,0 +1,45 @@
+# Architecture: Modular Monolith (C# + ASP.NET Core)
+
+## Project Structure
+```
+src/
+├── Modules/
+│   ├── Order/
+│   │   ├── OrderModule.cs
+│   │   ├── Controllers/OrderController.cs
+│   │   ├── Services/OrderService.cs
+│   │   ├── Repositories/OrderRepository.cs
+│   │   ├── Models/Order.cs
+│   │   ├── DTOs/CreateOrderDto.cs
+│   │   └── Events/OrderCreatedEvent.cs
+│   ├── Payment/
+│   │   └── ...
+│   └── User/
+│       └── ...
+├── Shared/
+│   ├── Database/ApplicationDbContext.cs
+│   ├── Events/IEventBus.cs
+│   └── Middleware/
+└── Program.cs
+```
+
+## Module Boundaries
+- Each module is self-contained with controllers, services, repositories
+- Modules communicate via events or explicit interfaces
+- No direct database access across module boundaries
+- Shared for cross-cutting concerns only
+
+## Conventions
+- Each module has a registration extension method (AddOrderModule)
+- Inter-module communication via MediatR notifications
+- Each module owns its EF Core configurations
+- Modules register their own DI services
+
+## File Naming
+- PascalCase: OrderService.cs
+- One module = one folder under Modules/
+
+## Testing
+- Per-module unit tests (xUnit)
+- Integration tests per module
+- Cross-module E2E tests

package/templates/architectures/modular/go-gin.md

@@ -0,0 +1,47 @@
+# Architecture: Modular Monolith (Go + Gin)
+
+## Directory Structure
+```
+internal/
+├── modules/
+│   ├── order/
+│   │   ├── handler.go
+│   │   ├── service.go
+│   │   ├── repository.go
+│   │   ├── model.go
+│   │   ├── events.go
+│   │   └── routes.go
+│   ├── payment/
+│   │   └── ...
+│   └── user/
+│       └── ...
+├── shared/
+│   ├── database/
+│   ├── events/event_bus.go
+│   └── middleware/
+├── config/
+│   └── env.go
+└── cmd/
+    └── main.go
+```
+
+## Module Boundaries
+- Each module is a Go package with its own handler, service, repository
+- Modules communicate via events or explicit function calls
+- No direct database access across module boundaries
+- Shared package for cross-cutting concerns
+
+## Conventions
+- Each module registers its own routes via a Setup function
+- Inter-module communication via event bus
+- Each module owns its database tables
+- Module interfaces defined per module
+
+## File Naming
+- snake_case: order_service.go
+- One module = one package under modules/
+
+## Testing
+- Per-module unit tests
+- Integration tests per module
+- Cross-module E2E tests

package/templates/architectures/modular/python-fastapi.md

@@ -0,0 +1,45 @@
+# Architecture: Modular Monolith (Python + FastAPI)
+
+## Directory Structure
+```
+src/
+├── modules/
+│   ├── order/
+│   │   ├── router.py
+│   │   ├── service.py
+│   │   ├── repository.py
+│   │   ├── models.py
+│   │   ├── schemas.py
+│   │   └── events.py
+│   ├── payment/
+│   │   └── ...
+│   └── user/
+│       └── ...
+├── shared/
+│   ├── database/connection.py
+│   ├── events/event_bus.py
+│   └── middleware/
+├── config.py
+└── main.py
+```
+
+## Module Boundaries
+- Each module is a Python package with its own router, service, repository
+- Modules communicate via events or explicit imports of public APIs
+- No direct database access across module boundaries
+- Shared package for cross-cutting concerns
+
+## Conventions
+- Each module registers its own FastAPI router
+- Inter-module communication via event bus
+- Each module owns its SQLAlchemy models
+- Public API defined in module __init__.py
+
+## File Naming
+- snake_case: order_service.py
+- One module = one package under modules/
+
+## Testing
+- Per-module unit tests (pytest)
+- Integration tests per module
+- Cross-module E2E tests

package/templates/architectures/modular/typescript-nestjs.md

@@ -0,0 +1,48 @@
+# Architecture: Modular Monolith (NestJS)
+
+## Directory Structure
+```
+src/
+├── modules/
+│   ├── order/
+│   │   ├── order.module.ts
+│   │   ├── order.controller.ts
+│   │   ├── order.service.ts
+│   │   ├── order.repository.ts
+│   │   ├── entities/order.entity.ts
+│   │   ├── dtos/create-order.dto.ts
+│   │   └── events/order-created.event.ts
+│   ├── payment/
+│   │   ├── payment.module.ts
+│   │   └── ...
+│   └── user/
+│       ├── user.module.ts
+│       └── ...
+├── shared/
+│   ├── shared.module.ts
+│   ├── database/
+│   ├── events/event-bus.ts
+│   └── guards/
+└── app.module.ts
+```
+
+## Module Boundaries
+- Each module is self-contained with its own controller, service, repository, entities
+- Modules communicate via events or explicit public APIs (exported services)
+- No direct database access across module boundaries
+- Shared module for truly cross-cutting concerns only
+
+## Conventions
+- Module exports define the public API
+- Inter-module communication via EventEmitter or message bus
+- Each module owns its database tables
+- NestJS DI scoped per module
+
+## File Naming
+- kebab-case: order.service.ts, create-order.dto.ts
+- One module = one directory under modules/
+
+## Testing
+- Per-module unit tests
+- Integration tests per module
+- Cross-module E2E 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,79 @@
+---
+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 main HEAD)..HEAD`
+2. Read spec and plan files
+3. Perform comprehensive review of all changes as a whole
+4. If @agents or /skills were specified, involve them in the review
+5. Save review to `.workflow/reviews/<name>-final.md`
+6. Present review findings to user
+
+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