Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions .cursor/rules/cannon-eng02-context.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
description: What Potato Cannon / ENG-02 left in this repo, and how to read it
globs: specs/002-smoke-build-info/**,.potato/**,.claude/**
alwaysApply: false
---

# What Cannon is doing to this repo

If you see `specs/002-smoke-build-info/`, a `.potato/` folder, or branches named `potato/HOM-*`, that is not stray product work — it is evidence of ENG-02, run against HomesFlow on purpose. Do not mistake it for real product scope.

## Short version

**Potato Cannon** (`potato-cannon` repo) is a kanban + agent orchestrator that runs Claude sessions through workflow phases with human approval gates. Rik uses it as the delivery mechanism for HomesFlow tickets going forward.

**Golden Thread** is HomesFlow's layer on Spec-Kit: immutable IDs (`FR-`/`AC-` per `traceability.md` §3) and Gate 1 / Gate 2 (`traceability.md` §6). Spec-Kit itself does not know about it.

**ENG-02** (spudnik) hypothesizes Cannon can drive HomesFlow's *real* installed spec-kit (`.claude/skills/speckit-*`) plus Golden Thread — not a hand-rolled approximation — with a kanban view and approval gates.

## Reference example: HOM-2

HOM-2 ("Stand up the Walking Skeleton") was the first end-to-end run of the `homesflow-speckit` template. Deliberately trivial (`FR-SMOKE-01`, `SMOKE` domain) — *not* real product scope, exempted from PRD-sourcing for that ticket only. Done. Read `specs/002-smoke-build-info/` for what a Cannon-driven ticket produces.

Notable from that run: real skills invoked (not reimplemented); Gate 1 caught `plan.md` self-certifying IDs missing from `spec.md`; a mid-run `chat_ask` was answered via Cannon's dashboard and the session resumed.

## Design decisions (Cannon side)

- Phase gates only where `traceability.md` §6 says work stops (before/after implement). Specify → Clarify → Plan → Tasks → Analyze = one continuous resumed session.
- No adversarial retry loops (`ralphLoop`/`taskLoop`). Real `speckit-implement` / `speckit-converge` already own that judgment.
- Promote/demote resumes the Claude session with a digest of new comments/Q&A/artifacts — not a full context rebuild.

## Still open

**Thread Cannon** (fork Cannon into a Spec-Kit + Golden Thread–specific tool) was deferred until the walking skeleton finished; that decision is live again, not settled.

## Go deeper

- `potato-cannon` + its CLAUDE.md
- `potato-cannon/apps/daemon/templates/workflows/homesflow-speckit/`
- spudnik `OBJECTIVES.md` (ENG-02), `docs/field-notes-pipeline.md` (FN-05)
- This repo's `traceability.md`
64 changes: 64 additions & 0 deletions .cursor/rules/newbie-homesflow.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
description: HomesFlow trial engineer orientation — Spec Kit, Golden Thread, craft/PR hygiene
alwaysApply: true
---

# Context Primer — HomesFlow trial engineer

You are joining HomesFlow as a trial collaborator. Your job is to deliver a thin slice the HomesFlow way: Spec Kit discipline, Golden Thread integrity, then craft/PR hygiene. Do not try to match prior agent diffs or invent product scope.

## How to work with Rik
- High-signal, direct, verify before asserting.
- Self-serve from the repo. Ask only when the PRD is silent or something is broken/off-repo.

## Read first (in order)
1. `CLAUDE.md` — entry + hard rules
2. `.specify/memory/constitution.md` — process/architecture law (Hierarchy of Truth)
3. `traceability.md` — Gate 2 mechanics
4. `HomesFlow.prd.md` — **product scope only**
5. `specs/001-mvp/dev-notes.md` — env + operational state
6. `specs/001-mvp/craft-conventions.md` — craft + delivery

## Hard rules
- **Product scope** comes only from `HomesFlow.prd.md`. Do not invent, extrapolate, or assume requirements. If the PRD is silent, ask or propose a PRD change — do not ship guessed behavior.
- **Process/architecture** comes from the constitution. Do not invent product behavior from the constitution, glossary, story map, or craft docs.
- **Story map** (StoriesOnBoard) is a human planning aid only — not Gate-2-enforced. Promote into the PRD when it becomes product truth.
- **Gate 2** proves the PRD is *true of the system* (IDs ↔ `@covers` ↔ `test_AC_*` or tracked debt). It does not prove the PRD is the right product.

## Spec Kit loop (expected)
For the assigned thin slice:
1. Confirm the authoritative IDs in `HomesFlow.prd.md` (Rik amends the PRD first if needed).
2. Fan into `specs/001-mvp/` (spec → plan → tasks) without minting new requirement IDs in the feature folder.
3. Implement only what tasks authorize; keep `Traces:` on every task.
4. Prove with `@covers` and `test_AC_*` (or leave unchecked tasks as tracked debt — never silent gaps).
5. Run `bash scripts/check-traceability.sh` before you call the slice done.

## Golden Thread (commands)
```bash
bash scripts/check-traceability.sh # must PASS
bash scripts/check-traceability.sh --json # per-ID detail
```
Coverage matrix (`coverage.md`) is a portfolio snapshot; CI enforces the gate script, not file freshness.

## Craft / PR hygiene
```text
feature branch → PR → craft-gate (+ Sonar) green → merge to main
```
- Branch naming for cloud agents: `cursor/<descriptive-name>-7716`
- Fill `.github/pull_request_template.md` (task IDs, Traces, Gate 2 evidence)
- Do not push product/craft changes straight to `main`
- Follow `craft-conventions.md` (SwiftLint, policy objects where logic is testable)

## Your trial assignment
Rik will give you **one micro acceptance criterion** newly added to the PRD (atomic, unit-testable). Take it through Spec Kit → implementation → Gate 2 green → PR.

**Success looks like:** clean Spec Kit artifacts, unbroken golden thread for that ID, and a reviewable PR.
**Non-goals:** matching a prior check-in’s code; rebuilding the thread visualizer; expanding scope “while you’re in there.”

## Local assumptions (confirm if relevant)
- Supabase local: `127.0.0.1:54321`; `Secrets.xcconfig` from `.example`
- Xcode: `cd ios && xcodegen generate`
- Paths: `ios/HomesFlow/`, `ios/HomesFlowTests/`

## Starting the session
Confirm: (1) you have the micro-AC ID and PRD text, (2) local vs cloud env, (3) any blockers not in `dev-notes`. Then proceed.
1 change: 1 addition & 0 deletions .potato/worktrees/HOM-1
Submodule HOM-1 added at 9bd6ae
1 change: 1 addition & 0 deletions .potato/worktrees/HOM-2
Submodule HOM-2 added at 9bd6ae
1 change: 1 addition & 0 deletions .potato/worktrees/HOM-3
Submodule HOM-3 added at 9bd6ae
21 changes: 6 additions & 15 deletions .specify/extensions.yml
Original file line number Diff line number Diff line change
@@ -1,23 +1,14 @@
installed:
- agent-context
- clewseau-gate
settings:
auto_execute_hooks: true
hooks:
after_specify:
- extension: agent-context
command: speckit.agent-context.update
after_implement:
- extension: clewseau-gate
command: speckit.clewseau-gate.check
enabled: true
optional: true
priority: 10
prompt: Execute speckit.agent-context.update?
description: Refresh agent context after specification
condition: null
after_plan:
- extension: agent-context
command: speckit.agent-context.update
enabled: true
optional: true
priority: 10
prompt: Execute speckit.agent-context.update?
description: Refresh agent context after planning
prompt: Run Clewseau Gate 2 traceability check?
description: Refuse silent gaps after implementation; refresh clew.json
condition: null
10 changes: 5 additions & 5 deletions .specify/extensions/.registry
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
{
"schema_version": "1.0",
"extensions": {
"agent-context": {
"version": "1.0.0",
"clewseau-gate": {
"version": "0.2.0",
"source": "local",
"manifest_hash": "sha256:9a1dc02d2d0139bb03860392ecacef79183be2c442feda2f9ccaa4e5907b1e47",
"manifest_hash": "sha256:c540ad473eb810d0952c51812571222b0d45b9f7aa5828d252d0cb5809110c89",
"enabled": true,
"priority": 10,
"registered_commands": {
"claude": [
"speckit.agent-context.update"
"speckit.clewseau-gate.check"
]
},
"registered_skills": [],
"installed_at": "2026-06-26T14:27:06.775090+00:00"
"installed_at": "2026-08-06T20:51:47.837406+00:00"
}
}
}
66 changes: 0 additions & 66 deletions .specify/extensions/agent-context/README.md

This file was deleted.

5 changes: 0 additions & 5 deletions .specify/extensions/agent-context/agent-context-config.yml

This file was deleted.

This file was deleted.

34 changes: 0 additions & 34 deletions .specify/extensions/agent-context/extension.yml

This file was deleted.

Loading