Planning Framework
How every item in every phase is structured. Apply uniformly.
1. Item ID scheme
Format: {PHASE}.{TRACK}-{N} where:
- PHASE = 0..4 or X (cross-cutting)
- TRACK =
C(Curva),P(Pasukuru BE),F(Pasukuru FE),I(Infra),T(Test),D(Decision) - N = sequence within phase+track
Examples:
0.C-1= Phase 0, Curva, item 11.F-3= Phase 1, Pasukuru FE, item 31.D-1= Phase 1 decision needed
2. Item template (every ticket follows this)
### {ID} — {Short Title}
**Track:** Curva | Pasukuru BE | Pasukuru FE | Infra | Test
**Jira:** CRV-?? / PASS-?? (filed: yes/no)
**Branch:** user/corone-{JIRA}-{slug}
**Depends on:** {list of item IDs}
**Blocks:** {list of item IDs}
**CC sessions:** {0.5 | 1 | 1.5 | 2 | 3}
**Wall-clock estimate:** {hours}
**Risk:** L | M | H
**Goal:** one-line outcome
**Files touched:**
- path/to/file (new | edit)
- ...
**Inputs / preconditions:**
- env vars needed
- data/fixtures
- API keys
**Acceptance criteria:**
- [ ] Concrete, testable assertion 1
- [ ] Concrete, testable assertion 2
- [ ] No regression in {existing flow}
- [ ] Migration runs+rollback both work
- [ ] Test added (unit/feature/e2e)
**Implementation steps:**
1. ...
2. ...
3. ...
**Test plan:**
- Unit: ...
- Integration: ...
- Manual: ...
**Rollout:**
- Feature flag: yes/no — name
- Migration: yes/no
- Backfill: yes/no
- Rollback path: ...
**Done when:** PR merged to develop + smoke test green + Jira moved to Done
3. Decision log template
When phase requires a fork in approach → file as {PHASE}.D-{N} decision item.
### {ID} — {Decision title}
**Status:** open | decided | superseded
**Owner:** Julian / Ryo / r_goto
**Deadline:** {date} (blocks {item IDs})
**Context:** why decision needed
**Options:**
1. **A** — pros/cons/effort
2. **B** — pros/cons/effort
3. **C** — pros/cons/effort
**Recommendation:** {option} because {reasoning}
**Decided:** {option chosen + date + rationale}
**Reversibility:** easy | hard | one-way-door
4. Definition of Ready (DoR) — before work starts
Item is READY when ALL true:
- Jira ticket filed with description matching template
- Branch name finalized
- Dependencies have status = Done OR explicitly pre-approved as parallel-safe
- Acceptance criteria written (no “TBD”)
- Files touched list reviewed (no surprise edits)
- Approval-gate decisions resolved if blocking
- CC session budgeted in current week’s plan
5. Definition of Done (DoD) — before merge
Item is DONE when ALL true:
- All acceptance criteria checked
- Tests added + passing locally
- CI green (HARD RULE — no merge with red CI per global policy)
- Lint + type-check clean
- PR opened with Jira ID in title + body
- PR body has
Requested by Julianattribution (kebahagiaan workspace) - Reviewer assigned (Ryo or eduson510)
- Merge requires explicit user approval (per ABSOLUTE rule)
- Jira ticket moved to Done after merge
- Vault log entry appended (
.wiki/log.md)
6. Tracking matrix (per phase)
Use a table per phase doc:
| ID | Title | Track | Jira | Branch | CC | Risk | Status | Depends | Blocks |
|---|---|---|---|---|---|---|---|---|---|
| 0.C-1 | … | C | CRV-100 | … | 1 | M | Ready | — | 0.C-2 |
Status values: Backlog | Ready | InProgress | Review | Done | Blocked
7. CC session sizing rubric
| Size | Estimate | What fits |
|---|---|---|
| XS | 0.25 session (~30min) | Single config / package add / type extension |
| S | 0.5 session (~1-2hr) | One small file new + 1 test |
| M | 1 session (~3hr) | New endpoint + service + DTO + test |
| L | 1.5 session (~4-5hr) | Multi-file refactor with migration |
| XL | 2-3 sessions (~1 day) | New module / payment integration / multi-tenant rework |
| XXL | 3+ sessions | Schema refactor / major architectural change — break down further |
Rule: if item ≥ XXL → MUST decompose. No XXL items in plan.
8. Parallelization plan
Three tracks run independently in parallel sub-agents (worktrees):
worktree-A: Curva (PHP) ──> Julian → eduson510 GitHub
worktree-B: Pasukuru BE (Nest) ──> Julian → time7676 GitHub
worktree-C: Pasukuru FE (Next) ──> Julian → time7676 GitHub
Sync points (mandatory):
- After Phase 0 completes → freeze contracts (webhook payload + identify endpoint)
- After Phase 1 completes → end-to-end smoke test before Phase 2
- After Phase 3 completes → joint demo before optional Phase 4
Anti-rules:
- ❌ No cross-repo refactor in one PR
- ❌ No contract change without contract-version bump
- ❌ No
git add .(stage by name per global rule)
9. Risk classification
| Risk | Definition | Mitigation must be in plan |
|---|---|---|
| L | Pure additive, no schema, no contract | optional |
| M | Schema migration OR contract addition | rollback path + feature flag |
| H | Contract breaking OR multi-tenant change OR security boundary | full rollback + canary tenant + sign-off gate |
Phase 0 has 1 H-risk item (HMAC signing — security boundary). Phase 4 (multi-shop) is entirely H-risk (schema breaking).
10. Communication contracts (versioned)
All cross-system payloads versioned. Header on every webhook + API call:
X-Integration-Version: 1
X-Integration-Signature: hmac-sha256=...
X-Integration-Timestamp: 1714896000
X-Integration-Nonce: {uuid}
X-Integration-Source: pasukuru | curva
Versions:
- v0 = current (bearer-only, no HMAC) — DEPRECATED after Phase 0
- v1 = HMAC + timestamp + nonce + source (Phase 0 ships)
- v2 = adds order events + line_user_id (Phase 0 ships, additive)
- v3 = adds LINE Pay events (Phase 3)
Rule: never break v_n. Add v_(n+1). Both supported until next major.
11. Feature flag inventory
Each user-visible behavior change behind a flag. Names registered here:
| Flag | Default | Owner | Removed at |
|---|---|---|---|
integration.webhook.v1_hmac | off | Pasukuru BE | Phase 1 stable |
integration.order_events | off | Pasukuru BE | Phase 1 stable |
integration.curva_inbound_receiver | off | Curva | Phase 1 stable |
liff.enabled | off | Pasukuru FE | Phase 2 stable |
liff.auto_identify | off | Pasukuru FE | Phase 2 stable |
flex.pasukuru_picker | off | Curva | Phase 3 stable |
payment.line_pay | off | Pasukuru BE | Phase 4 stable |
multi_shop | off | both | n/a (kept) |
Flag impl: env var FEATURE_* checked at boot + per-tenant override in DB if needed.
12. Approval-gate checklist (per phase)
Before phase starts:
- All decisions in this phase resolved
- All Jira tickets filed
- All ITEMS marked Ready (DoR satisfied)
- Test fixtures prepared
- Feature flags created (off)
- Rollback rehearsed for any M/H risk item
Before phase ends:
- All items DoD satisfied
- Smoke test green
- Vault updated (log + page)
- Memory persisted
- User sign-off recorded
13. CC session etiquette
Each CC session begins with:
bash .wiki/check.sh(vault health)- Read this framework doc
- Read current phase doc
- Pick ONE item with status=Ready
- Move to InProgress
- Work to DoD
- Open PR, do NOT merge
- Update vault log
- Move to Review
Each CC session ends with:
- Vault updated
- Memory saved if facts learned
- TodoWrite cleared for finished items
- Notes for next session if mid-flight
14. Estimation calibration
These estimates assume:
- Caveman-mode CC (terse, no preamble)
- Single focused goal per session
- All deps green
- No surprise scope
Add multiplier for:
- × 1.5 if first time touching that module
- × 2 if discovering schema/test gaps
- × 0.7 if work isolated in single file
Re-estimate at end of each phase. Update this doc.