tf-plan

name	tf-plan
description	Write a project PRD (functional + non-functional + constraints + risks) and break it into 18-22 tasks (with model recommendations). A heavyweight planning step for thinking hard before writing code.
disable-model-invocation	true
allowed-tools	Bash, Read, Glob, Grep, Write, Edit
argument-hint	["프로젝트 설명 또는 아이디어"]

Marblo Project Planning

The step where you think and plan thoroughly before writing a single line of code. This skill does not create tasks. It only builds the plan. Once the plan is finalized, execute it with /tf-start.

Difference from /tf-analyze: /tf-analyze is a quick sketch of components, roles, and dependencies (minutes). /tf-plan is the heavyweight version that covers writing a PRD + decomposing into 18-22 tasks + identifying non-functional requirements/constraints/risks (tens of minutes to hours).

4 phases: ① 8 required + 5-7 additional Socratic questions → ② PRD (features, NFR, constraints, KPIs, system diagram, risks, assumptions) → ③ 18-22 task decomposition (with model recommendations) → ④ review checklist.

---

⛔ Required rule: Marblo MCP only

Never use the Claude Code built-in tools (TaskCreate, TaskList, TaskUpdate, TaskGet). All task-related work MUST use the Marblo MCP tools: create_tasks_bulk, create_task, get_all_tasks, get_available_tasks, claim_task, update_task_status, add_activity, submit_for_review, check_feedback, get_task_activities, get_agent_skill, get_task_dependencies

Tasks created with Claude Code's built-in TaskCreate do not show up on the Marblo dashboard.

---

Phase 0: Lock the project name

Lock the project name to be used by /tf-start first.

1. Propose or ask the user for a project name:

   📦 Please decide on a project name.
   e.g.: youtube-insight, todo-app, my-saas
   (lowercase letters + hyphens recommended; this name is used on every task ticket)
   

2. After user approval, record this name in the PRD.
3. Use this project name consistently for all subsequent task creation.

---

Phase 1: Brainstorming (Socratic questioning)

Concretize the user's idea. Don't design right away — ask questions first. Entering design while still ambiguous produces a wrong PRD and wrong tasks.

Required questions — 8 (do NOT move on until all are answered)

A. Problem & users

1. Core value: "What problem does this project solve? In one sentence."
2. Persona pain point: "How do users solve this problem today? Why is that insufficient?"
3. User scale: "Expected number of users at MVP launch? (10? 100? 100,000?)"

B. Scope & success metrics

4. Core features: "If you had to pick just 3 must-have features?"
5. Success metrics: "What does success look like? 1-3 measurable metrics. (DAU, response time, conversion rate, etc.)"
6. Scope check: "Build the MVP first and expand, or go full-feature from the start?"

C. Tech & operations

7. Tech preference: "Do you have a preferred tech stack? Why that choice? (recommend one if none)"
8. Operating environment: "Where does it run? (local/Docker/AWS/Vercel...) Budget constraints? Schedule constraints?"

Additional questions — 5-7 as needed (only the relevant ones)

• External dependencies: "Do you need external API integration?" (auth, payments, social login, LLM, etc.)
• Data source: "Where does the data come from?" (user input, external API, crawling, file upload)
• Competition/differentiation: "Are there similar services? How are we different?"
• Regulation & security: "Do you handle personal/payment/medical data? Subject to regulations like GDPR/PCI-DSS?"
• Performance SLO: "Do you have a response-time target? (p50/p95) Concurrent-user target?"
• Accessibility & i18n: "Need i18n? What WCAG accessibility level?"
• In-house operations: "Who on the team operates it? Where do monitoring/alerts go?"

Principle: don't move to Phase 2 until all 8 required answers are clear. Ask additional questions only to the extent ambiguity remains, then stop. If "I don't know" is the answer, state the most reasonable assumption and record it in the PRD's Assumptions section.

---

Phase 2: Write the PRD (Product Requirements Document)

Organize the brainstorming results into a structured document.

PRD template

# [Project name] PRD

## One-line summary

[What this project is, in one sentence]

## Core problem

[The problem to solve + how users solve it today + why that is insufficient]

## Target users

- **Primary persona**: [e.g.: solo founder in their 30s, sales-team PM]
- **Expected scale**: [N users at MVP launch, M after 6 months]
- **Usage context**: [when/where/why they use this]

## Success metrics (KPI)

| Metric           | Target         | Measurement |
| ---------------- | -------------- | ----------- |
| [e.g.: DAU]      | [e.g.: 100]    | [tool]      |
| [e.g.: p95 resp] | [e.g.: ≤500ms] | [APM]       |
| [e.g.: conv.]    | [e.g.: 5%]     | [Analytics] |

## Tech stack

- Backend: [e.g.: FastAPI + PostgreSQL]
- Frontend: [e.g.: Next.js 14 + Tailwind CSS]
- AI/API: [e.g.: Claude API, YouTube Data API]
- Infra: [e.g.: Docker Compose, Vercel, AWS Fargate]

## System diagram

```text
[Show core components + data flow as an ASCII or Mermaid block]

Example (ASCII):
  ┌────────┐   HTTPS    ┌──────────┐   SQL    ┌──────────┐
  │ Browser├───────────►│  FastAPI ├─────────►│ Postgres │
  └────────┘            └────┬─────┘          └──────────┘
                             │ HTTP
                             ▼
                       ┌──────────┐
                       │ Claude API│
                       └──────────┘
```

Core features (MVP)

1. [Feature 1] — [one-line description]
2. [Feature 2] — [one-line description]
3. [Feature 3] — [one-line description]

Screen list

Screen	Path	Key elements
[name]	/path	[inputs, buttons, data, ...]

API endpoints

Method	Path	Description	Auth
POST	/api/xxx	[desc]	JWT
GET	/api/xxx	[desc]	public

DB tables

Table	Key columns	Relations
users	id, email, name	—
posts	id, user_id, title	→ users

Non-functional requirements (NFR)

• Performance: [e.g.: p50 ≤200ms, p95 ≤500ms / 100 req/s concurrent]
• Availability: [e.g.: 99.5% (MVP), 99.9% (1.0)]
• Security: [e.g.: HTTPS-only, bcrypt, OWASP Top 10 check]
• Data/regulation: [e.g.: personal data GDPR/PIPA, payments PCI-DSS, medical HIPAA]
• Accessibility: [e.g.: WCAG 2.1 AA / keyboard navigation]
• i18n: [e.g.: ko, en — i18n-ready or ko-only]
• Observability: [e.g.: structured logs, Sentry, p95 alerts]

Constraints

• Budget: [e.g.: within $100/month infra cost]
• Schedule: [e.g.: MVP 4 weeks, β 8 weeks]
• Team: [e.g.: 1 full-stack / Backend 2 + Frontend 1]
• External dependencies: [e.g.: Stripe not supported in Korea → use Toss]
• Technical constraints: [e.g.: OAuth integration with existing system required]

Risks

Risk	Impact	Prob.	Mitigation
[tech]	High	Med	[PoC, identify backup library]
[schedule]	Med	High	[define scope-cut trigger]
[external]	High	Low	[confirm SLA, fallback path]

Assumptions

Record the items that were "I don't know" in Phase 1 and the reasonable guesses. A broken assumption triggers a PRD re-review.

• [Assumption 1 + what happens if it's wrong]
• [Assumption 2]

NOT in scope

• [Thing 1 excluded from MVP]
• [Thing 2 excluded from MVP]

### PRD writing rules

- **Be specific**: "user management" ✗ → "email+password login, profile editing" ✓
- **Be measurable**: "fast" ✗ → "API response within p95 500ms" ✓
- **State exclusions**: writing down what you won't do prevents scope creep
- **State assumptions**: pin "I don't know" areas as assumptions — verifiable later

---

## Phase 3: Task decomposition

Decompose the PRD into Marblo tasks.

### Decomposition principles

1. **Size**: 1 task = 1-2 hours of work. Split if larger, merge if smaller.
2. **Unit**: 1 API endpoint = 1 task is a good baseline.
3. **Dependencies**: only set depends_on where there is a real ordering. Independent ones run in parallel.
4. **scope**: pre-assign the files each task modifies → prevent Git conflicts.
5. **Verification**: state "completion criteria" for each task (tests pass, API response confirmed, etc.).

### Decomposition order (dependency graph)

Layer 1: Foundation (no dependencies) ├── DB schema/model design ├── Project initial setup └── Independent utilities

Layer 2: Core API (depends on Layer 1) ├── API endpoint A ├── API endpoint B └── Auth/permissions

Layer 3: Frontend (depends on Layer 2) ├── Screen A ├── Screen B └── Shared components

Layer 4: Integration (depends on Layers 2, 3) ├── Integration tests ├── E2E tests └── Docker/deployment

### Task card format

Organize each task in this format:

TASK-001: [title] role: backend | frontend | test | devops model: opus | sonnet | haiku # ← model recommendation (see guide below) priority: 5(urgent) ~ 1(low) depends_on: [TASK-NNN, ...] scope: [file paths to modify] completion criteria: [what "done" looks like — measurable] expected deliverables: [list of files to create/modify]

### Model recommendation guide

Match the model to task complexity to optimize cost and speed.

| Complexity | Model | Suitable tasks                                                  |
| ------ | ------- | --------------------------------------------------------------- |
| High   | **opus**   | Architecture design, DB schema + migrations, complex algorithms, AI prompt engineering, security/auth implementation |
| Medium | **sonnet** | General API endpoints, business logic, React screens, integration tests, Docker/CI pipelines |
| Low    | **haiku**  | Simple CRUD, static UI components, docs/comments, env-var cleanup, small fixes |

> **Principle**: when in doubt, go one level up. opus costs more than sonnet, but it's cheaper than rework.

---

### Per-category task decomposition templates

Each category provides 18-22 standard tasks. Drop or merge some to fit your project's
characteristics. **Don't cut the lower bound of 18 too easily** — tests, observability, and docs
are always needed later.

#### A. SaaS web app (18-22 tasks)

=== Layer 1: Foundation === TASK-001: Project initial setup (devops, sonnet, p:5) — repo, lint, formatter, basic CI skeleton TASK-002: DB schema design + migrations (backend, opus, p:5) — ERD, indexes, constraints TASK-003: Env vars/secret management (devops, haiku, p:5) — .env.example, secrets policy

=== Layer 2: Auth & core API === TASK-004: Auth system (backend, opus, p:5, deps:002) — JWT/session, bcrypt, refresh TASK-005: User profile API (backend, sonnet, p:4, deps:004) — GET/PATCH /me TASK-006: Core domain API #1 (backend, sonnet, p:4, deps:002) — CRUD 1 TASK-007: Core domain API #2 (backend, sonnet, p:4, deps:002) — CRUD 2 TASK-008: Authorization/RBAC middleware (backend, opus, p:4, deps:004) — per-role guards

=== Layer 3: Payments & external integration === TASK-009: Payment integration (backend, opus, p:3, deps:004) — webhook, idempotency TASK-010: Email/notification system (backend, sonnet, p:3, deps:004) — transactional mail

=== Layer 4: Frontend === TASK-011: Design system/shared components (frontend, sonnet, p:4, deps:001) TASK-012: Login/signup UI (frontend, sonnet, p:4, deps:004) TASK-013: Dashboard screen (frontend, sonnet, p:3, deps:006) TASK-014: Core feature screen #1 (frontend, sonnet, p:3, deps:007) TASK-015: Settings/profile screen (frontend, haiku, p:2, deps:005) TASK-016: Payment/subscription management screen (frontend, sonnet, p:3, deps:009)

=== Layer 5: Quality & operations === TASK-017: Unit tests (test, sonnet, p:2, deps:008) — core API/business logic TASK-018: E2E tests (test, sonnet, p:2, deps:014) — golden path TASK-019: Observability (devops, sonnet, p:2, deps:008) — logs/metrics/Sentry TASK-020: Docker + CI/CD (devops, sonnet, p:2, deps:017) TASK-021: README/ops docs (devops, haiku, p:1, deps:020) TASK-022: Security review (test, opus, p:2, deps:020) — OWASP checklist

#### B. Data pipeline (18-20 tasks)

=== Layer 1: Foundation === TASK-001: Project setup + environment (devops, sonnet, p:5) TASK-002: Data model/schema (backend, opus, p:5) — raw / staged / mart TASK-003: Secret/external credential management (devops, haiku, p:5)

=== Layer 2: Ingestion === TASK-004: Data source #1 connector (backend, sonnet, p:5, deps:003) TASK-005: Data source #2 connector (backend, sonnet, p:5, deps:003) TASK-006: Ingestion scheduler (devops, sonnet, p:4, deps:004) — cron / Airflow / Cloud Scheduler TASK-007: rate-limit/retry/idempotency (backend, opus, p:4, deps:004) — retry/dedup

=== Layer 3: Transform & AI === TASK-008: Data cleaning/validation (backend, sonnet, p:4, deps:002) — Pydantic/Pandera TASK-009: Data transform ETL (backend, sonnet, p:4, deps:008) TASK-010: AI analysis/summary module (backend, opus, p:4, deps:009) — prompts, result validation TASK-011: Result storage/cache (backend, sonnet, p:3, deps:010)

=== Layer 4: Output & observability === TASK-012: REST API for querying results (backend, sonnet, p:3, deps:011) TASK-013: Dashboard UI (frontend, sonnet, p:3, deps:012) TASK-014: Download/Export (CSV/JSON) (backend, haiku, p:2, deps:012) TASK-015: Data quality monitoring (devops, sonnet, p:3, deps:008) — null/drift alerts

=== Layer 5: Quality & operations === TASK-016: Unit tests (test, sonnet, p:2, deps:010) TASK-017: Integration tests (test, sonnet, p:2, deps:013) TASK-018: Cost monitoring (devops, sonnet, p:2, deps:010) — AI/storage cost alerts TASK-019: Docker + CI/CD (devops, sonnet, p:2, deps:016) TASK-020: Ops docs/runbook (devops, haiku, p:1, deps:019)

#### C. Chrome extension/bot (18-20 tasks)

=== Layer 1: Foundation === TASK-001: Project setup + manifest v3 (devops, sonnet, p:5) TASK-002: Build pipeline (vite/webpack) (devops, sonnet, p:5) TASK-003: Secret/API key storage policy (backend, opus, p:5) — chrome.storage / safeStorage

=== Layer 2: Core logic === TASK-004: Core domain module (backend, opus, p:5, deps:001) TASK-005: External API client (backend, sonnet, p:4, deps:003) TASK-006: rate-limit/retry/cache (backend, sonnet, p:4, deps:005) TASK-007: Background service worker (backend, opus, p:4, deps:004) TASK-008: content script + page messaging (backend, sonnet, p:4, deps:007)

=== Layer 3: UI === TASK-009: Shared UI components (frontend, haiku, p:3, deps:002) TASK-010: Popup UI (frontend, sonnet, p:4, deps:004) TASK-011: Options/settings page (frontend, sonnet, p:3, deps:010) TASK-012: Side panel/overlay (frontend, sonnet, p:3, deps:008) TASK-013: First-run onboarding (frontend, haiku, p:2, deps:010)

=== Layer 4: Permissions & security === TASK-014: Permission request/verification flow (backend, opus, p:3, deps:007) — least-privilege TASK-015: User consent/telemetry (backend, sonnet, p:2, deps:014)

=== Layer 5: Quality & operations === TASK-016: Unit tests (test, sonnet, p:2, deps:004) TASK-017: Integration/E2E tests (test, sonnet, p:2, deps:012) — Playwright + extension load TASK-018: Store listing assets (devops, haiku, p:2, deps:017) — screenshots, description, policy TASK-019: CI auto build/packaging (devops, sonnet, p:2, deps:002) TASK-020: User docs/FAQ (devops, haiku, p:1, deps:018)

> **Cases where task count shrinks**: no real operations (personal side project),
> no external payments/auth, single screen, etc. Even so, **don't drop tests/CI/docs**.

---

## Phase 4: Review + finalize

Show the plan to the user and get confirmation.

### Review checklist

**PRD completeness**
- [ ] Are all core features covered by tasks?
- [ ] Are the success metrics (KPI) measurable?
- [ ] Are the non-functional requirements (performance/security/regulation/accessibility/observability) stated?
- [ ] Are the constraints (budget/schedule/external dependencies) stated?
- [ ] Are risks + mitigations identified?
- [ ] Are assumptions stated, with a clear plan for when they break?
- [ ] Are the NOT-in-scope items clear?
- [ ] Does the system diagram show the core data flow?

**Task decomposition completeness**
- [ ] Is the task count within the proper range (18-22)? (state the reason if it deviates)
- [ ] Is the dependency order correct? (no circular dependencies?)
- [ ] Do task scopes not overlap?
- [ ] Are task sizes appropriate? (not too large/small? 1-2 hours each?)
- [ ] Does each task have a model recommendation (opus/sonnet/haiku)?
- [ ] Are test / CI/CD / docs tasks not missing?
- [ ] Are the completion criteria measurable?

### After finalizing

1. Save the PRD file in the project: `docs/PRD.md`
2. Tell the user:
   > "The plan is finalized. Run `/tf-start` to create tasks and have agents begin work."

> **Important**: do NOT run `create_tasks_bulk` at this step. Only build the plan.
> **Important**: the PRD MUST include the project name. `/tf-start` creates tasks under this name.