AXP-Resurection/docs/speckit-beginner-and-001-preplan-briefing.txt

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
================================================================================