peach-gen-spec

Spec generation skill

New feature Spec-driven developmentto proceed, a single Spec file is generated.

Target flow:

peach-team-ui-proto
→ peach-gen-spec proto=<ui-proto 태스크 경로>
→ peach-gen-db spec=<생성된 Spec 경로>
→ peach-team-dev spec=<생성된 Spec 경로>
→ peach-team-e2e spec=<생성된 Spec 경로> [proto=<ui-proto 태스크 경로>]

Core principles

The Spec is the Source of Truth for implementation criteria.
PRD is not considered. Even if an input document exists, it is merely source material, and implementation criteria follow only what is stated in the final Spec.
The standard deliverable is single .md file.
Spec은 team-dev와 team-e2eis confirmed enough that it can proceed without additional planning questions.
team-*Test code, selectors, fixtures, and suite-internal implementation that it will handle on its own are not written in the Spec.
Instead, requirements per TEST_ID, completion criteria, Backend TDD criteria, Store/Contract criteria, UI criteria, and E2E scenarios are sufficiently specified.
Status codes are not created for operational reporting. User reporting prioritizes plain text (확정, 구현완료, 검증완료, 차단).
A mandatory matrix is not created. Permissions/states/errors/external dependencies are primarily prose, and are expanded into a table only when branches and rules are numerous enough that a table is clearer.
FKs (Foreign Keys) are not created. Referential integrity is handled in the application.
test-datais not a copyable answer key but a baseline skeleton. Subsequent gen-*/team-* skills can adapt to the domain within Bounded Autonomy.
The target Spec length is 250–450 lines. If small, around 200 lines is allowed, but TDD/E2E criteria are not omitted.
If the user requests discussion before modification, do not modify the document immediately; instead proceed in the order of 분석 → 권장안 → 사용자 확정 → 문서 반영 . The AI does not overuse questions and first presents a reasonable default, but for decisions that are hard to reverse—such as DB structure, state transitions, external integrations, and permission flows—it obtains user confirmation.
TDD/E2E criteria are not filled in without blanks for every requirement. So that team-dev/team-e2e can autonomously supplement, core business transitions, storage results, permission/ownership blocking, representative failure casesonly are specified.
E2E는 only core user flows are written. Start data is prepared directly by the scenario/suite, and if the same flow repeats, suite combinationis prioritized. Unit scenario writing rules (single responsibility/reuse/independent execution) are peach-e2e-scenario, and suite integration rules are peach-e2e-suite가 SoT다.
If there are external integrations, authentication, payment, files, notifications, or mock data, environment-specific behavior(whether local/dev mock is allowed, prod-prohibited paths) is confirmed in prose in §5 Permissions/States/Errors/External Dependencies.
Spec은 VerifiabilitySpecify. Separate what is automatically verified, what cannot be verified, and where it is dangerous to system safety in §5.5/§6/§12.5. This definition must be clear so that team-dev/team-e2e can branch between the automated area and the user confirmation area.

File structure

docs/spec/{년}/{월}/[개발자아이디]-[YYMMDD]-[한글기능명].md

예:

docs/spec/2026/05/{개발자아이디}-260506-공지사항-게시판.md

Developer ID should preferentially use whoami, and if that fails, use git config user.name.

Deliverable structure

Part A: At a glance

This is the section where a person quickly checks the essence of the feature.

Section	Policy
Summary card	Mandatory. What/who/key actions/new and changed tables/verification points
Core flow	Recommended. Sequence diagram of 1–3 user actions
Data model	Recommended. Express only new/changed tables as an erDiagram
Additional diagrams	Optional. Only when there is a state machine or special flow

Deprecated:

System architecture diagram: it is the standard pitch harness structure, so its information value is low.
UI flow diagram: ui-proto is the primary source. If there is no ui-proto, replace it with the screen criteria table in Part B.

Part B: Confirmed Spec

team-dev, team-e2e, gen-dbis the execution standard that is read first.

Section	Policy	Purpose
Meta	Mandatory	Module name, feature name, UI pattern, reference materials
1. Feature scope	Mandatory	CRUD, special actions, file/Excel/external integration
2. Screen/action criteria	Mandatory	ui-proto-based screens, actions, success/error states
3. DB schema criteria	Mandatory	Columns/indexes/references that gen-db can use to create migrations
4. API contract	Mandatory	Request/response criteria for Backend/Store/Contract to align on
5. Permissions, state, errors, external dependencies	Mandatory	Criteria to prevent implementation omissions (including 5.5 system safety)
6. TEST_ID requirements	Mandatory	Requirements, completion criteria, verification level
7. Backend TDD criteria	Mandatory	Behaviors to verify, not test code
8. Store/Contract criteria	Mandatory	API response keys and Store state criteria
9. UI implementation criteria	Mandatory	Screen states, buttons, toasts, validation messages
10. E2E scenarios	Mandatory	User flows, inputs, expected results
11. File/module boundaries	Mandatory	Directories to create/modify
12. Exclusions/prohibitions	Optional	Out-of-scope features and prohibited implementations (including 12.5 unverifiable areas)
13. References	Obligation	ui-proto, schema, feature documents, guide code

What is excluded from the Spec

Item	Responsibility
Test code, describe/it details	`peach-team-dev`
selector, wait, fixture, suite code	`peach-team-e2e`
Execution history, Ralph Loop history	`docs/qa/`, `docs/e2e-suite/`
4-axis state matrix (S/U/I/V)	Not used
PRD traceability table	Not used

Required: Determine DB type

When the skill runs, it first reads the target project's env file to determine the DB type.

api/src/environments/env.local.yml

DATABASE_URL Criteria:

URL	Mode
`postgresql://...`	PostgreSQL
`mysql://...`	MySQL

Type criteria:

Purpose	PostgreSQL	MySQL
PK	serial4	INT AUTO_INCREMENT
Integer	int4	INT
Big integer	int8	BIGINT
Datetime	TIMESTAMP	DATETIME
Reference value	int4	INT

The type mapping SoT is peach-gen-db/references/type-mapping.md. When changing, update both sides together.

Input scenario

Scenario	Input argument	Description
ui-proto based	`proto=<ui-proto 태스크 경로>`	Recommended. Extract Spec from a finalized screen plan
Improve existing	`feature-docs=<경로>` or context injection	Generate change Spec based on peach-doc-feature output
Natural language/conversation	None	Collect a small new feature through conversation
Reinforce DB draft	`schema=<경로>`	Read existing schema/DDL/ERD drafts together to reinforce based on DB
Discussion/confirmation	User requests "before modification", "only the essentials", "modify after direction is confirmed"	Return only analysis, recommendations, and confirmation questions without directly modifying the document

Execution form:

/peach-gen-spec proto=<ui-proto 태스크 경로>
/peach-gen-spec proto=<ui-proto 태스크 경로> schema=<schema 또는 DDL 경로>
/peach-gen-spec feature-docs=<기능별설명 폴더>
/peach-gen-spec

Workflow

Step 0: Input mode branching

proto=<경로> 있음        → ui-proto 기반 모드
feature-docs=<경로> 있음 → 기존 개선 모드
schema=<경로> 있음       → DB 초안 보강
인자 없음                → 자연어/대화 모드
사용자가 "수정 전/핵심만/방향 확정 후 수정" 요청
                         → 토론/확정 모드 (문서 수정 보류)

In discussion/confirmation mode, respond only in the following order and do not modify files.

1. 현재 이해
2. 미확정 판단
3. 권장안
4. 사용자 확인 질문
5. 사용자 확정 후에만 문서 반영

Step 1: Data collection

In addition to ui-proto/feature documents, Check current implementationbriefly. Do not write the results at length in the Spec; compress to 현행 구조 기반 확장 / 신규 생성 / 제외 about this much.

DB: existing tables/columns/state values/indexes
Backend: API, service, dao, transaction, approval/processing flow
Frontend: screens, store, contract, modal, route
TDD: existing helper, fixture, cleanup patterns
E2E: existing scenario, suite, seed/data preparation method

Next, if ui-proto based, read the following materials.

# 메타
<PROTO_PATH>/_task-meta.ts

# 현업 검토용 설명/기획 개요
<PROTO_PATH>/overview/pages/overview.vue

# 화면 파일
<PROTO_PATH>/**/pages/*.vue

# Mock 데이터
<PROTO_PATH>/**/mock/*.mock.ts

# Mock Store
<PROTO_PATH>/**/store/*.store.ts

# 타입
<PROTO_PATH>/**/type/*.ts

If in improve existing mode, feature-docsread the overview document first, then read only the necessary detailed documents additionally.

If there is schema input, read tables/columns/indexes/reference relationships and reflect them in the Spec's DB schema criteria.

Step 2: Confirm basic information

Module name: English kebab-case
Table name: snake_case
Korean feature name: for file names
One-line description
UI pattern: crud / two-depth / select-list / page / excel
File upload: none / regular file / image / regular file + image
Storage method: none / Local / S3
DB type: PostgreSQL / MySQL

Step 3: Confirm feature scope

Basic CRUD:

Paged list (findPaging)
Keyword/select list (findList)
Detail view (detailOne)
Create (insert)
Update (update)
Change usage status (updateUse)
Logical delete (softDelete)

If there are special actions, specify them separately from CRUD.

예:

Approve / Reject
Excel upload / download / template download
Bulk change
File preview / download
Send notification
External API sync

Step 4: Confirm screen/action criteria

Extract the following from ui-proto, and confirm only ambiguous parts with the user.

Screen list: list, detail, create, update, modal, tab, bulk processing, etc.
Main actions: search, save, delete, approve, reject, upload, download, etc.
Input fields: required/optional, type, length, selectable values
List columns: column name, sort, display conditions
Success states: toast, modal closed, list refreshed, navigate to detail, status changed
Error states: required field validation, permission failure, server error, external integration failure
Empty states: 0 list items, no search results, no files

Step 5: Confirm DB schema criteria

Confirm the following so that gen-db can create migrations directly.

New/changed tables
Column name, type, required or not, description, selectable values, default value
Index candidates
Logical reference relationships (no FK creation)
Whether to apply common columns: is_use, is_delete, insert_seq, insert_date, update_seq, update_date
DB change candidates and confirmation criteria

DB design does not just list columns. Briefly leave the following decisions.

Adopted structure and reason
Excluded structure and reason
unique criteria
Whether a history table is needed
Whether to apply or exclude soft delete / common audit columns (may be excluded if it does not fit by nature, such as single-record status tables, log-type tables, or external ledger tables; if excluded, specify in §12 Exclusions/Prohibitions)
FK prohibited (referential integrity is handled in the application)

If ambiguous, DB_DECISION_REQUIREDand leave it as such, but if possible, confirm with the user during the Spec creation step and finalize.

Step 5.5: Confirm system safety

Within §5 permissions, states, errors, and external dependencies, system safety Specify the subsection. Preemptively block at the Spec stage the class of "decisions that work but are systemically dangerous" pointed out in the Karpathy interview (e.g., using an external email as an identifier to match payment and login).

Confirm the following items in prose. If not applicable, write "Not applicable", but if there are too many "Not applicable" entries, flag it as suspicious in the §7.5 self-check.

Identifier policy: what is the PK, and are external inputs (email, phone) used as identifiers
Data ownership boundary: whose data can be viewed/modified by whom
Cross-matching prohibition: keys that must not be used for matching between two systems
Regression risk marker: does this feature touch authentication/session/common modules (Y/N)

Step 6: Finalize API contract

team-dev와 team-e2especify the request/response so that they observe the same criteria.

endpoint
method
query/path/body
response shape
error response
Whether file upload uses multipart
pagination key: list, totalRow, page, rowSize and other existing patterns take precedence

Do not write code implementation examples. Write only the contract.

Step 7: Finalize TEST_ID + TDD/E2E criteria

By default, one TEST_ID per requirement.

Recommended format:

R-001, R-002 ...

If the domain is clear, add a prefix.

NOTICE-001, NOTICE-002 ...

The §6 TEST_ID table lists all requirements (requirement + completion criteria + verification grade).

Verification grade (Step 4)

Assign one of the following to each TEST_ID. Depending on the grade, team-dev/team-e2e branch between the automated area and the user confirmation area.

Grade	Meaning	Handling
Automated (high)	Types, tests, contracts	team-dev/e2e automated
Automated (medium)	Business rules	Automated after TEST_ID mapping
Human (medium)	Permissions, cross-matching, system safety	User confirmation required
Human (low)	Aesthetics, copy, real-transaction accuracy	No automated loop; also state in §12.5

§7 Backend TDD, §10 E2E는 Do not cover all TEST_IDs. Select and write only the core verifications.

Backend TDD selection criteria (write only those that apply)

Core state transitions (e.g., draft → approval request → approved)
Save/update results (field values, audit columns, history table)
Permission or ownership scope blocking
Representative failure cases (external integration failure, concurrent updates, duplicates)
Responsibility for test data creation/cleanup

Simple CRUD basic behavior (required-value validation, normal insert, normal update) is handled by team-dev as a standard pattern, so do not write it in the Spec.

E2E scenario selection criteria

Keep only core user flows as unit scenarios.
Do not "assume existing data is present." The starting data is prepared directly by the scenario/suite.
If the same flow is repeated across multiple TEST_IDs, suite combinationtakes precedence.
Do not write selector, wait, fixture, or suite-internal code.
The rules for writing unit scenarios (single responsibility/reusability/independent execution) and the suite integration rules are peach-e2e-scenario / peach-e2e-suiteIt is SoT. Only flow intent is placed in the Spec.

예:

TEST_ID: NOTICE-001 (등록 흐름 — 핵심)
Backend TDD: 등록자/등록일 저장 + 필수값 검증
E2E 단위: 빈 목록 → 등록 → 필수값 입력 → 저장 → 목록에 노출

TEST_ID: NOTICE-005 (승인 흐름 — 상태 전이)
Backend TDD: 승인요청 → 승인 상태 전이, 권한 차단
E2E 단위: 등록된 공지 → 승인요청 → 관리자 로그인 → 승인 → 상태 변경 확인

E2E suite: 공지 라이프사이클
  단위(등록) → 단위(승인) → 사용여부 변경 → 삭제

Step 7.5: Verifiability self-check

Before generating the Step 8 file, self-check the following 5 questions. If any one is problematic, report it to the user, reinforce it, and then proceed to Step 8.

Is a verification grade assigned to every TEST_ID?
In §5.5 System Safety, are there 5 or more "Not Applicable" items? (If so, suspect it and re-review)
Is there any place that uses external input (email, phone, external system ID) as an identifier?
Are changes to auth/session/_common expected? If so, specify Y in the §5.5 regression risk markers.
Is the §12.5 unverifiable area empty? Reconfirm from the perspectives of aesthetics, copy, real transactions, and external integration safety that it truly is absent.

This check is intended to separate, at the Spec stage, the jagged intelligence area pointed out by Karpathy. Leave the check result as one line in the completion report.

Step 8: Generate file after user confirmation

single .md Generate one file.
assets/spec-template.mdRead and replace.
Only items for which user confirmation has been completed are written as 확정.
Undecided items are left as DECISION_REQUIRED or DB_DECISION_REQUIRED, and are reported as blocked items in the completion report.

template

spec-template.mdRead and replace.

Main placeholders:

Placeholder	Meaning
`FEATURE_NAME_KR`	Korean feature name
`DESCRIPTION`	One-line description
`MODULE_NAME`	Module name
`TABLE_NAME`	Table name
`DB_TYPE`	PostgreSQL/MySQL
`STATUS`	Draft/Confirmed/Blocked
`SOURCE_REFERENCES`	ui-proto/schema/feature document path
`SUMMARY_*`	Part A summary card
`SEQUENCE_DIAGRAM_BODY`	Core flow sequence body
`ER_DIAGRAM_BODY`	Data model erDiagram body
`FUNCTION_SCOPE`	CRUD/special actions/file features
`SCREEN_ACTION_CRITERIA`	Screen/action/success/error criteria
`SCHEMA_COLUMNS`	DB column table body
`SCHEMA_INDEXES`	Index SQL
`REFERENCE_RELATIONS`	Logical reference relationships
`DB_CHANGE_CANDIDATES`	DB change candidates
`API_CONTRACTS`	API contract
`RULES_PROSE`	Permissions/status/errors/external dependencies
`SYSTEM_SAFETY`	System safety (identifiers/ownership boundaries/no cross-matching/regression risk)
`REQUIREMENT_MATRIX`	TEST_ID requirements matrix (including verification grade)
`TDD_CRITERIA`	Backend TDD criteria
`STORE_CONTRACT_CRITERIA`	Store/Contract criteria
`UI_IMPLEMENTATION_CRITERIA`	UI implementation criteria
`E2E_SCENARIOS`	E2E unit scenarios
`E2E_SUITES`	E2E integration suite (optional)
`MODULE_BOUNDARIES`	File/module boundaries
`FORBIDDEN_ITEMS`	Exclusions/prohibitions
`UNVERIFIABLE_AREAS`	Unverifiable areas (no automated verification, user confirmation areas)
`REFERENCE_INDEX`	Reference index

Completion conditions

□ DB 종류 판별 완료
□ ui-proto/기능 문서/schema 입력 자료 확인 완료
□ 기능 범위 확정
□ 화면/액션/성공/오류 기준 확정
□ DB 스키마 기준 확정 또는 DB_DECISION_REQUIRED 명시
□ API 계약 확정
□ §5.5 시스템 안전성 확정 (식별자/소유 경계/교차 매칭/회귀 위험)
□ TEST_ID 요구사항 매트릭스 확정 (검증 등급 포함)
□ Backend TDD 기준 확정
□ Store/Contract 기준 확정
□ UI 구현 기준 확정
□ E2E 시나리오 확정
□ §12.5 검증 불가 영역 명시 (없으면 "해당 없음")
□ §7.5 검증성 자가 점검 5개 질문 통과
□ 제외/금지 사항 확인
□ 단일 Spec 파일(.md) 생성 완료
□ team-dev/team-e2e가 추가 기획 질문 없이 실행 가능한지 자체 점검 완료

Post-completion guidance

Spec 생성이 완료되었습니다.

산출물: docs/spec/{년}/{월}/[개발자]-[YYMMDD]-[기능명].md

다음 단계:
1) DB 마이그레이션 생성
   /peach-gen-db spec=docs/spec/.../[기능명].md

2) 본 개발
   /peach-team-dev [모듈명] mode=fullstack spec=docs/spec/.../[기능명].md

3) E2E 검증
   /peach-team-e2e spec=docs/spec/.../[기능명].md [proto=<ui-proto 태스크 경로>]

If the user wants to continue subsequent implementation in a separate session/worktree, provide the following handoff information together.

- 대상 저장소
- 기준 브랜치 / feature branch 추천명
- Spec 문서 경로
- Spec 확정 커밋
- worktree 추천 경로 (peach-worktree 스킬 활용 가능)
- team-dev 실행 명령
- team-e2e 실행 명령
- commit/push 전 사용자 확인 원칙

Example

For Spec-driven development examples, examples.mdRead only when necessary.

Precautions

Do not create a PRD traceability section. The implementation baseline is the Spec.
Proceed with questions step by step, but if context is sufficient, steps may be combined.
Small single edits may be handled with a short note without enforcing a formal Spec.
Do not repeatedly generate system architecture diagrams.
Do not create a 4-axis state matrix (S/U/I/V).
Permissions/state/errors/external dependencies are primarily prose, and are expanded into a table only when complex.
TDD/E2E are finalized not as code but as verification criteria and scenarios.
Requirements not in the Spec are team-dev와 team-e2edoes not implement arbitrarily.
Verifiability is the responsibility of the Spec. Do not leave §5.5 System Safety, §6 Verification Grade, and §12.5 Unverifiable Areas blank. If left blank, downstream cannot automatically identify jagged areas.