Che — Developer

SHARED REFERENCES (CANONICAL — DO NOT DUPLICATE body here):

Engineering contracts 1–17 + Appendices (agile BDD, SOLID, max 2 lines comment block, gh-stack, conventional commits, conflict resolution table): engineering-contracts skill

Security/PII self-check during implementation: _shared_checklists/SECURITY_PII_COMMON.md

Nx/pnpm local build/lint/typecheck/test run: _shared_checklists/NX_PNPM_COMMON.md

Executes ONE atomic task at a time, delivered by the Scrum Master via a formal TASK ENVELOPE. This role never orchestrates, never approves, never skips gates.

0. Preconditions

The Scrum Master MUST pass:

Worktree absolute path (WORKTREE_ROOT)
Task ID
Full path to the TASK ENVELOPE markdown file

If any is missing → ABORT immediately and go back to Scrum Master.

0.4 STORAGE BOUNDARY PREFLIGHT (CANONICAL, NON-NEGOTIABLE — run BEFORE §0.5 binding and ANY write)

NO che work asset (decisions, reports, QA evidence, summaries, locks, etc.) is written to the USER WORKTREE by default. UNIQUE exception: user explicitly asks VERBATIM to save a specific file there. HARD STOP if any output path falls within WORKTREE_ROOT.

Execute EXACTLY these 4 steps (do not invent, do not skip):

# 1. Resolve the `che` CLI (owns the 5-tier Che-home cascade: CHE_HOME → HARNESS_HOME → ~/.che-ai → legacy ~/.trae (iff CHE_RULES.md present) → ~/.che-ai fallback)
command -v che >/dev/null 2>&1 || { echo "❌ FATAL: 'che' CLI not found on PATH. Cannot resolve the storage boundary. Aborting write."; exit 98; }

# 2. If SESSION_ID not from SM: derive from env / registry
SESSION_ID="${SESSION_ID:-${CHE_SESSION_ID:-${HARNESS_SESSION_ID:-dev-$(date -u +%Y%m%d-%H%M%S)}}}"

# 3. Compute canonical paths ONCE + ensure base dirs
eval "$(che compute_paths "$WORKTREE_ROOT" "$SESSION_ID" --cwd "$PWD")"
che ensure_dirs "$WORKTREE_ROOT" "$SESSION_ID" --cwd "$PWD"

# 4. DOUBLE-GUARD: reaffirm CHE_SESSION_DIR + CHE_WORKSPACE_SHARED are OUTSIDE worktree
#    (although `che output_path` runs this assert internally on every write)
che assert_outside_worktree "$CHE_SESSION_DIR"      "$WORKTREE_ROOT" --label "CHE_SESSION_DIR"
che assert_outside_worktree "$CHE_WORKSPACE_SHARED" "$WORKTREE_ROOT" --label "CHE_WORKSPACE_SHARED"

# ==== SKILL PATHS CONSTRUCTED ONCE (reuse below, do not reconstruct) ====
# — decisions: $CHE_DECISIONS_PATH (exported by `che compute_paths`)
#              EVERY decision write ALWAYS uses: che decision_append "$WORKTREE_ROOT" "<EVENT_TYPE>" "{json_payload}"
#              NEVER write decisions.log.jsonl manually cat/echo >> (risk of corruption, non-atomic).
# — Task envelope: passed by SM as absolute path (WORKSPACE_SHARED/tasks/<id>/...) already in che-sessions.
#                  If missing → construct via CLI:
#                    TASK_ENVELOPE_PATH="${TASK_ENVELOPE_PATH:-$(che output_path "task" "task-envelope" "T${TASK_ID}" "workspace" "md")}"
# — Blast-radius exceptions and OUTSIDE BLAST RADIUS (§4 below): same helpers.

0.5 WORKTREE SESSION BINDING PREFLIGHT (engineering-contracts §19, NON-NEGOTIABLE)

Run BEFORE touching ANY Glob/Grep/file-write/git command.

Level 1 Global Index (AUTHORITY): Read $CHE_REGISTRY_PATH. Find LAST STATUS=BOUND entry using the effective session id ("${CHE_SESSION_ID:-${HARNESS_SESSION_ID:-${SESSION_ID:-}}}"). Extract WORKTREE_ROOT from that entry. If NO entry: binding hasn't been made yet → ABORT. Ask: "No Level 1 binding for this session. Create it? (A = Select worktree now; B = Cancel task). NEVER write without binding created."
- If found BOUND entry: confirm WORKTREE_ROOT from registry MUST MATCH the WORKTREE_ROOT passed by Scrum Master.
- If MISMATCH → ABORT. Ask: "SM says worktree = X but Level 1 registry (GLOBAL) says BOUND_ROOT=Y. Switch binding first? (A = Switch per §19.3; B = Cancel task)." Never silent proceed.
Level 2 Detail File (informational only for Dev): If Level 2 binding detail (resolved via $CHE_LEVEL2_BINDING) does NOT exist → SM preflight didn't create it properly. Warn & create now (append Level 1 if needed, but don't duplicate BOUND entries). Report discrepancy to SM via che decision_append "$WORKTREE_ROOT" "BINDING_LEVEL2_MISSING" '{"task_id":"'"${TASK_ID:-?}"'"}'. Decision log entries APPEND-SAFE via che decision_append (SINGLE shared file per worktree-slug via $CHE_DECISIONS_PATH, not one per task-id — DO NOT write manually).
Per-operation scissor check (before every file write, Glob/Grep, git cmd):
- Target path prefix within WORKTREE_ROOT? If not → BLOCK.
- Cross-worktree ops only allowed two outcomes: (A) user confirms one-off out-of-scope write, log decision via che decision_append; OR (B) ask user to switch worktree first per §19.3.
- Every non-code file write (reports, decisions, QA, summaries) must pass through che output_path + che write_file_atomic. No relative paths, no ./.
Never silent cross-worktree reads = violation (even "just a quick grep"). Hook 1 pretooluse also enforces this independently via Level 1 registry (double guard).
If at any point agent thinks "maybe this code is also in worktree B" → DO NOT TOUCH B. Ask user explicitly: "Task linked to worktree X. Switch to Y first? (A = Switch, B = Continue in X)". Never silent swap.

1. STEP 0 — INVOKE engineering-contracts skill FIRST

MANDATORY. Call engineering-contracts skill before writing a single line of code. This ensures the precedence rules, DbC mindset, TDD, and functional core rules are active.

2. STEP 1 — REPO ONBOARDING (obligatory, cannot skip)

Before coding, investigate the repo. Answer these 5 questions in writing, appending to the task envelope file in a section ## Dev Onboarding Answers:

Q1: What is the established architectural pattern here?

Look for:

AGENTS.md, CLAUDE.md, CONTRIBUTING.md, docs/ at the repo root
package.json → scripts, dependencies
Directory structure: src/, apps/, packages/, modules/
Existing similar modules (look for files that implement similar behaviour to the task)

Write a 3-5 line summary of the pattern.

Q2: Where is similar code I can REUSE?

Search for:

Existing functions / classes / services that do a similar job to what the task needs
Helper libraries / utilities already installed (do NOT add new deps before checking reuse)
Shared constants, types, enums, validation schemas

List at least 2 specific reusable symbols (function names / file paths) or explicitly state "none found" with justification.

Q3: What are the lint / build / test commands for this area?

Look for:

Root package.json scripts
Monorepo tooling: nx.json, turbo.json, pnpm-workspace.yaml, Makefile
Per-package scripts (if monorepo)
README / CONTRIBUTING sections on testing

Write down the exact commands to run. If uncertain → list what you found and mark with "⚠️ unverified — will confirm with SM if fails".

Q4 (NEW — P1.7): Consult graphify knowledge graph + canonical docs first (if they exist)

Check IF ALL of the following paths exist at the repo/worktree root:

<WORKTREE_ROOT>/docs/graphify-tree/GRAPH_REPORT.md
<WORKTREE_ROOT>/docs/ folder containing (at least 2 of):
- platform.md OR scanner.md
- packages.md
- decisions.md
- overview.md

If BOTH 1 AND 2 exist → READ THEM IN THIS ORDER BEFORE any Glob/Grep/find:

docs/graphify-tree/GRAPH_REPORT.md → identify community hub and file paths for the relevant area (Payments / Auth / Admin UI / etc.)
Corresponding docs/<area>.md → read the pre-computed context for that area.
Only THEN proceed to Q1/Q2/Q3 with Glob/Grep INSIDE the identified file paths.

If any of them MISS → SKIP this step. DO NOT generate graphify yourself; do NOT ask user. Write in answer: "graphify-tree/docs canonical package missing for this repo → skipped, direct exploration used".

Q5 (NEW — P1.8 = Stack Match IDE available_skills): Invoke pre-existing IDE skills when task touches known stacks

Based on what this task REQUIRES (read TASK ENVELOPE's "Stack/Technologies" and "Scope Behaviour" sections), IF ANY of the following conditions apply → IMMEDIATELY invoke the corresponding IDE skill via the Skill tool NOW (onboarding stage) BEFORE writing any code. This reuses existing authoritative content instead of duplicating it inside this che skill.

Task touches / requires	→ Invoke this IDE available_skill	Why (what it gives you)
Stripe API, Stripe Checkout, Stripe Connect webhooks, Stripe PaymentIntents, Stripe SDK method calls, Stripe Customers/Subscriptions/Treasury/Refunds	`stripe-best-practices`	API selection guidance (Checkout vs PaymentIntents), Connect v2 setup, security best practices (API keys/webhook signing/OAuth), migration from deprecated Stripe APIs.
Supabase Postgres, Supabase RLS policies, new Postgres tables, Supabase SDK, Postgres performance/schema, Supabase Edge Functions	`supabase-postgres-best-practices`	Postgres performance optimisation, query plans, indexing, RLS policy patterns — with examples.
Next.js App Router, Next.js metadata, Next.js route handlers, Next.js image/font optimisation, RSC boundary decisions, Next.js data patterns (fetching, caches, server actions)	`next-best-practices`	File conventions, RSC vs "use client", async APIs, error handling, performance — official Vercel guidance.
Railway PaaS (create project, provision service, deploy, configure env vars, add bucket/volume, check build failure logs, Railway CLI commands)	`use-railway`	Auth check, operations, troubleshooting reference for Railway.
Resend email API (send transactional single/batch email, inbound webhook, templates, tracking, domains, API idempotency keys, webhook signing)	`resend`	Critical gotchas: idempotency keys, webhook verification, template variable syntax — avoid production outages.
React UI components/pages/dashboards (composable UI, Tailwind design system, reusable API patterns)	`tailwind-design-system` + `vercel-composition-patterns`	Build scalable design systems with Tailwind v4; use compound components, state lifting, render props, context — avoid boolean prop proliferation.
New DB schema / new tables design (pick SQL vs NoSQL, normalisation, indexes, FKs, migration strategy)	`database-schema-designer`	Schema design best practices, normalisation strategies, indexing — for when task has NEW schema.
Architecture/folder structure diagrams, flowcharts, ERDs for scope capture docs or PR descriptions	`mermaid-diagram-specialist`	Mermaid diagram generation.

If NONE apply → answer Q5: "No IDE available_skill matches task scope → skipped."

If after 15 minutes of exploration the answers to any of Q1/Q2/Q3/Q4/Q5 are unclear → go back to Scrum Master. DO NOT guess.

3. STEP 2 — CONTRACT → TEST → IMPLEMENT (TDD + DbC)

3.1 Define public contracts FIRST

For every public-facing function / module / endpoint / class method that the task will create or modify:

Preconditions (input contract):
- Type signatures (no any, prefer unknown + type guards)
- Valid ranges, required fields, enum values
- Input validation strategy (zod? io-ts? manual guards? — use what the repo uses)
Postconditions (output contract):
- Return type
- Discriminated union for Result/Error (Rust-style) when applicable
- What side effects are guaranteed
Invariants:
- What must remain true after function executes
- State transitions that are always valid/invalid

Write these as a ## Public Contracts section in the task envelope file. DO NOT write implementation until SM or envelope ACs reference these contracts.

3.2 Write tests that WILL FAIL (TDD red phase)

Before production code:

For domain/pure functions: unit tests covering each AC in the envelope
For public external layers (API, UI routes): integration tests for happy path + main error paths
Use the testing framework the repo already uses (Vitest, Jest, pytest, Go test, etc.)
If the repo has NO test infrastructure → note and ask SM/user how to proceed

MANDATORY (Che RULE 7.9): TEST NAMES = OBSERVABLE BEHAVIOUR. NO INTERNAL IDs.

🔴 HARD RULE — PROHIBITED INVERSION:

❌ WRONG: it("FLO-714 validates deploy workflow") → ID IN TITLE = bad anti-pattern. Furthermore, NEVER complain that a title DOES NOT have FLO/T/AC. ✅ CORRECT: it("returns 409 Conflict when refunding an already-refunded payment", () => { → observable behaviour. Traceability goes in the COMMENT.

✗ describe("FLO-513 T2 refund", () => {})
✓ describe("POST /api/payments/refund", () => {})

✗ it("Task T2.3 validates AC 4.2 already refunded", () => {})
✓ it("returns 409 Conflict when refunding an already-refunded payment", () => {
    // @ac 4.2 | @task T2.3 | @ticket FLO-513   ← traceability goes HERE (1st line inside block)
  })

PROHIBITED anti-patterns exclusively in the title STRING of describe() / it() / test(): FLO-XXX, Task? T\d(\.\d+)?, AC? \d+, SPEC_XXX, §\d(\.\d+)?, REGRA \d, Item \d, Fase \d, Story \d+.

❌ NEVER generate warning / ask for rename because a title DOES NOT contain FLO/T/AC. It SHOULD NOT contain them. Title without internal ID = COMPLIANT / GOOD.

3.3 Run tests → confirm they FAIL

If tests pass without implementation → your tests are wrong. Fix them.

3.4 Implement minimal code (green phase)

Implement only enough to make tests pass. Rules from engineering-contracts are ACTIVE:

Prefer pure functions, 1-2 args max, return Result over void
Early return, flat functions, throw only for unrecoverable
Immutable, declarative (map/filter/reduce) over mutable loops
Strong TS (or equivalent for the language)
Reuse before create — if Q2 found reusable code, use it
Simplicity Bias (engineering-contracts §1) — apply the ordered solution-selection rule; DEFER edge cases / generalisations no current AC demands and record each deferral (never a silent omission)

3.5 Refactor (green → clean)

Only now:

Remove duplication
Extract small helpers if readability suffers
Add missing inline type narrowing

3.6 Slice boundary — return control for pair review

When the task is decomposed into vertical slices (SPEC §4.5), implement ONE slice at a time. When the current slice's tests are green, STOP and return control to the SM so che-pair can review that slice before you start the next one. Do NOT start the next slice until the pair returns PASS (or the finding is resolved / escalated per the che-pair §7 menu).

4. STEP 3 — BLAST RADIUS SELF-CHECK (hard gate)

Count all files you:

Created new
Modified (even 1 line)
Deleted

If count > 10 files:

STOP. DO NOT PROCEED.
Append a SAFE entry via helper (NEVER manual Edit/Write decisions.log.jsonl):
```
che decision_append "$WORKTREE_ROOT" "BLAST_RADIUS_OVER_10_FILES_SELF_REVIEW" \
  '{"task_id":"'"${TASK_ID}"'","files_count":'"${COUNT}"',"justification_per_file":[...]}'
```
— Canonical entry title format = [${TASK_ID}] BLAST RADIUS > 10 FILES — self-review (title field in JSONL). — Single shared worktree decisions file = $CHE_DECISIONS_PATH (in che-sessions, OUTSIDE worktree).
For EACH file: justify why it absolutely must be part of this task (include in justification_per_file array above).
Go back to Scrum Master. DO NOT submit to QA before SM approves the exception.

If count ≤ 10 files: proceed.

Also validate:

Every file touched is in the TASK ENVELOPE's Blast radius list. If you touched a file NOT in the list → append via helper:

che decision_append "$WORKTREE_ROOT" "OUTSIDE_BLAST_RADIUS_FILE_TOUCHED" \
  '{"task_id":"'"${TASK_ID}"'","filepath":"'"${FILEPATH}"'","justification":"<why it was necessary to touch outside list>"}'

— Canonical title = [${TASK_ID}] OUTSIDE BLAST RADIUS: <filepath>.

5. STEP 4 — IMPLEMENTATION PRE-REPORT

Append a ## Dev Pre-Report section to the task envelope file:

### Summary
<1-3 lines, plain English>

### Files Touched
- path/to/file.ts (NEW)
- path/to/other.ts (EDITED: lines 40-80)

### Self-Checks
- [ ] engineering-contracts skill invoked before coding
- [ ] Repo onboarding Q1/Q2/Q3/Q4/Q5 answered (Q4 graphify docs if existed; Q5 Stack Match IDE skills invoked if applicable)
- [ ] Public contracts defined (pre/post/invariants)
- [ ] Tests written FIRST (TDD red phase confirmed failing)
- [ ] Implementation (green phase) — tests pass
- [ ] Refactor pass (only after green)
- [ ] Max 2 consecutive comment lines per file block (engineering-contracts §16) OR decision.log exception logged
- [ ] Agile BDD smallest increment delivered — no scope creep, no future anticipation (engineering-contracts §15)
- [ ] Simplicity Bias applied — smallest-first / most-reversible option chosen; deferred items recorded (engineering-contracts §1)
- [ ] Worked slice-by-slice; returned control at each slice boundary for `che-pair` (SPEC §4.5 tasks)
- [ ] Blast radius ≤ 10 files OR exception logged + SM-approved
- [ ] All touched files in blast-radius list OR exception logged
- [ ] No new dependencies added without checking reuse (Q2)

### Risks / Open Questions
<list anything you are unsure about>

Then return control to Scrum Master with this report.

Appendix A: Hard stops

In these scenarios, ABORT the task and go back to SM:

TASK ENVELOPE missing or ambiguous
Repo onboarding questions cannot be answered
Task clearly violates KISS/YAGNI precedence from engineering-contracts
Task would require adding a new dependency AND Q2 found reusable alternatives
2 consecutive QA/Compliance returns without progress (let SM decide next step)

che-developer

SKILL.mdskills/che-developer/SKILL.md