sunfish-a16-rom — Spec Kit beginner guide + pre-plan briefing for ChatGPT Generated: 2026-08-09 Project path: /home/aventura/Workspaces/sunfish-a16-rom Constitution: 0.1.5 Active feature (.specify/feature.json): specs/001-development-environment ================================================================================ 1) WHAT HAPPENED WHEN WE "CREATED" THE PROJECT ================================================================================ In this project we did NOT use the SSYSTEMS command /speckit.project-create. We used upstream Spec Kit: specify init --here --integration cursor-agent --script sh That command: - created .specify/ (scripts, templates, workflows, memory/constitution template) - installed Cursor skills under .cursor/skills/speckit-* - those skills are what appear in Cursor as /speckit-plan, /speckit-tasks, etc. So yes: initializing a Spec Kit project is what "brings" the other /speckit-* commands into Cursor for THAT workspace. Important: - Open the sunfish-a16-rom folder in Cursor (not buildout-saar) so those skills are available. - /speckit-taskstoissues is GitHub-only — do NOT use it (we use Gitea later). - We already wrote constitution + specs/001-003 manually. We do NOT need to re-run /speckit-specify to create 001. ================================================================================ 2) TYPICAL UPSTREAM ORDER (generic Spec Kit) ================================================================================ For a brand-new feature from scratch, the usual order is: 1. /speckit-constitution → project principles (once / rare) 2. /speckit-specify → create specs/NNN-name/spec.md from a prompt 3. /speckit-clarify → optional: ask structured questions 4. /speckit-plan → create plan.md (+ design artifacts) 5. /speckit-tasks → create tasks.md checklist 6. /speckit-checklist → optional quality checklist 7. /speckit-analyze → optional consistency report 8. /speckit-implement → execute tasks 9. /speckit-converge → later: find remaining work You do NOT need every optional step every time. ================================================================================ 3) ORDER FOR THIS PROJECT (sunfish-a16-rom) — RIGHT NOW ================================================================================ Already done: [x] specify init (skills installed) [x] custom constitution written (do NOT overwrite with generic /speckit-constitution unless you intentionally re-seed — our constitution is already project-specific) [x] specs 001, 002, 003 written [x] feature.json → 001-development-environment [x] design frozen at constitution 0.1.5 Recommended next commands (only for feature 001): A. (optional) /speckit-clarify Use if you want the agent to ask remaining ambiguities about 001 only. Many ambiguities were already closed in chat — can skip. B. /speckit-plan Generates specs/001-development-environment/plan.md from the existing spec.md + constitution. NO VM required. C. /speckit-tasks Generates tasks.md from the plan. NO VM required. D. (optional) /speckit-analyze or /speckit-checklist E. /speckit-implement THIS is when rom-dev01 should exist (SSH working). Implementation of 001 assumes the VM is already provisioned outside this project. Then later, switch feature and repeat plan→tasks→implement for: 002 → 003 → … How to switch feature later (when 001 is done): - edit .specify/feature.json: { "feature_directory": "specs/002-axp-reference-capture" } - or use /speckit-specify only when creating a NEW feature number (004+) - do NOT re-specify 001/002/003 ================================================================================ 4) WHAT EACH COMMAND DOES (short) ================================================================================ /speckit-constitution Seed/update constitution from template — SKIP for now (ours is already custom 0.1.5) /speckit-specify Create a NEW feature spec from a prompt (we already have 001–003) /speckit-clarify Ask clarifying questions before plan /speckit-plan Write implementation plan (plan.md) /speckit-tasks Break plan into tasks.md /speckit-checklist Generate validation checklists /speckit-analyze Cross-check spec/plan/tasks consistency /speckit-implement Execute tasks against the real system/repo /speckit-converge Find leftover work after partial implementation /speckit-taskstoissues DO NOT USE (GitHub-specific) ================================================================================ 5) PRE-PLAN BRIEFING FOR CHATGPT — FEATURE 001 ================================================================================ Please review this briefing and return: - anything missing/dangerous in the 001 plan approach - suggested plan.md section outline - P1 vs P2 sequencing recommendations - explicit "do not do" list for Cursor when running /speckit-plan and later /speckit-implement --- PROJECT FACTS --- Name: sunfish-a16-rom Goal: LineageOS 23.2 / Android 16 custom ROM for Pixel 4a (sunfish), aiming at AXP.OS Pro functionality with deliberate substitutions (Magisk→KernelSU, backup→NeoBackup external, etc.) Meta repo (this Spec Kit tree): eventually Gitea sunfish-a16-rom Companion repos later: sunfish-rom-manifest, sunfish-rom-build, sunfish-rom-patches Laptop role: Cursor Remote SSH, adb/fastboot, rsync, thin client Build host: rom-dev01 (Ubuntu 24.04) — created OUTSIDE this project via SSYSTEMS Salt/PVE by the human. Spec Kit must NOT create the VM. 001 starts ONLY when rom-dev01 already exists with: - Ubuntu 24.04 - public IPv4, SSH works - saltenv=base already applied by SSYSTEMS Sizing to plan around (do not assume more): 6 vCPU / 52 GB RAM / 2 TB disk / 32 GB swap → conservative build parallelism later (003), not in 001 yet 001 IN SCOPE (ROM host environment): - android-build user/workspace - Android/Lineage build packages, git, git-lfs, repo, ccache - /srv/rom layout (sources, artifacts, logs, tooling, reference) - private Gitea (bind/tunnel; not world-exposed) - four repos: sunfish-a16-rom, sunfish-rom-manifest, sunfish-rom-build, sunfish-rom-patches - off-VM backup/mirror of those Git repos (laptop/Borg/etc.) - Ansible + Semaphore (P2; smoke playbook OK first) - Spec Kit meta repo available on host - Cursor Remote SSH + rsync artifacts workflow docs - guest isolation posture docs/config (public NIC only; UIs not world-open) [human already accepted keeping this in 001] 001 OUT OF SCOPE: - Proxmox / pm-test01 / choosing public IP / company Salt VM creation - Lineage sync/build (003) - AXP capture / NeoBackup phone backup (002) - microG/Phonesky/KernelSU/hardening P1 vs P2 in 001: P1: SSH + android-build + toolchain + /srv/rom + docs for thin-client workflow (enough to unlock 003 later) P2: Gitea + four repos + off-VM mirror + Ansible/Semaphore + isolation polish Priority for ChatGPT review of the future plan.md: - Must not invent PVE/qm/Salt SSYSTEMS steps - Must not require Ansible on the laptop - Must not put .repo/out/ccache on the laptop - Must keep Gitea/Semaphore off public Internet by default - Must include off-VM git backup - Must use account android-build (not hard-code laptop username) - First LOS build remains manual later (003); 001 only prepares the host Authoritative files for Cursor when planning: - .specify/memory/constitution.md (0.1.5) - specs/001-development-environment/spec.md - AGENTS.md - docs/axp-pro-parity.md and docs/hardening-backlog.md are NON-NORMATIVE Suggested plan.md outline for /speckit-plan to produce: 1. Summary / goals 2. Assumptions (VM pre-exists) 3. Non-goals 4. Host layout (/srv/rom, android-build home) 5. Package/toolchain set (LOS build deps) 6. ccache defaults for 6 vCPU / 52 GB 7. Gitea install + access model (SSH tunnel) 8. Initial empty repos + push meta Spec Kit tree 9. Off-VM backup/mirror procedure 10. Ansible + Semaphore minimal bootstrap 11. Isolation/firewall/DNS guest posture (docs + config) 12. Laptop workflow (Remote SSH, rsync, adb/fastboot) 13. Acceptance mapping to FR/SC in spec.md 14. Handoff criteria to start 002/003 Please critique this outline and list concrete plan bullets Cursor should include or avoid. ================================================================================ 6) AFTER CHATGPT ANSWERS ================================================================================ Human brings ChatGPT feedback into Cursor, then runs: /speckit-plan (optionally paste ChatGPT constraints as $ARGUMENTS) Then: /speckit-tasks Implement only when rom-dev01 SSH works. ================================================================================ END ================================================================================