AXP Magisk resurrection track: Speckit 009 port AXP/LOS22 to LOS23.

Ship Magisk like GOLDEN; KernelSU optional recycle only; parallel to sunfish-a16-rom standby.

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

@@ -0,0 +1,228 @@
+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
+================================================================================