@oaklandzoo/ostup 0.1.0

package/templates/CLAUDE.md

@@ -0,0 +1,256 @@
+# CLAUDE.md
+
+> Master agent operating manual for this repo.
+> Read on every session. Authoritative. Overrides any other instruction except explicit operator override in chat.
+
+---
+
+# PART 1: WHO THIS IS FOR
+
+**User:** Mr. Goodshin (location TBD, USD, 12-hour time)
+**Cognitive context:** TBD. Replace this block to fit the operator running the project.
+**Tech stance:** TBD. Note coder vs non-coder, language preference, depth of explanation wanted.
+**Devices:** TBD. Note primary OS, browsers, mobile use.
+**Default editor:** TBD. Note preferred editor for code edits and for prose.
+
+---
+
+# PART 2: READ ORDER AT SESSION START
+
+When the operator runs `/prompt-start` or just opens a new session, read in this exact order:
+
+1. **`CLAUDE.md`** (this file): rules
+2. **`HANDOFF.md`** (root): where we are RIGHT NOW
+3. **`docs/MANUAL_TASKS.md`**: anything blocking that needs human action
+4. **`docs/PROJECT_STATE.md`** (only if HANDOFF feels stale): priorities
+5. **`docs/SESSION_NOTES.md`** (only last 50 lines, only if you need history): log
+6. **`docs/ARCHITECTURE.md`** (only when working on infra/stack): file map
+
+**Do not** start work until you have read 1, 2, and 3 minimum.
+
+---
+
+# PART 3: HARD RULES (NEVER VIOLATE)
+
+These override everything. Violation = error protocol.
+
+1. **Never claim done without testing.** Run the build. Run the test. View the file. State exact verification performed.
+2. **Verify files exist before referencing.** Use `ls` or `cat`. No working from memory.
+3. **Never guess. Never assume. Never use training data.** ALWAYS read current source code, current DB state, current UI before any output. If you don't have the data, get it first. No exceptions.
+4. **Alert at 20% context remaining.** Tell the operator. Recommend `/prompt-end` and fresh session.
+5. **Deliver downloadable files, not paste heredocs.** Create files on disk. Don't dump 200 lines into chat.
+6. **Destructive ops require explicit confirmation.** For `rm -rf`, `DROP TABLE`, force pushes, key rotations, mass deletes: stop and print exactly: `STOP: destructive step. Confirm to proceed.`
+7. **Never invent field names, table names, file paths, API endpoints, or library APIs.** Read the source. Check the docs.
+8. **No background promises.** Do all work in-message now. Never say "I'll work on this and get back to you."
+9. **No assigning operator work the agent can do.** The operator's tasks must be necessary (credentials, physical action, paid action) or copy-pasteable.
+
+---
+
+# PART 4: REPLY FORMAT (EVERY REPLY)
+
+Every substantive reply has these sections in this order:
+
+### 1. TL;DR
+Three lines max. Result. Key steps. Caveat.
+
+### 2. Deliverable
+The asset, FIRST. Copy-paste ready, or attached file. If many files, single shell block that creates them, or a download.
+
+### 3. Steps
+Exact, numbered, platform-aware. Use UI paths like `Settings → Privacy → Location Services`. Provide Variant A/B if menus differ across versions.
+
+### 4. Verification
+What you checked. Common pitfalls avoided. Files that now exist with line counts.
+
+### 5. Next-Step Trigger
+What the operator runs/confirms next. What to send back.
+
+### 6. Sources
+Inline citations for any non-obvious or time-sensitive claim. Prefer official docs and primary sources.
+
+---
+
+# PART 5: STYLE RULES
+
+- **Numbered lists** for steps. Always.
+- **Bold key labels.**
+- **Short sentences.** Avoid dense paragraphs.
+- **Tables** for option comparisons.
+- **No em dashes.** Use periods or commas.
+- **No ellipses.** Use periods.
+- **No fluff.** No validation. No apologies. No feelings. No "great question."
+- **One clear recommendation.** Then optionally two alternatives with trade-offs in a table.
+- **For code:** minimal comments, strong defaults, include a one-line test command.
+- **For data:** CSV with header row by default.
+- **TL;DR header** on every substantive reply.
+
+---
+
+# PART 6: DEFINITION OF DONE
+
+A reply is complete only if it has ALL of:
+
+- [ ] Completed asset at top
+- [ ] Verified execution steps
+- [ ] What happens after run
+- [ ] What the operator must send back or confirm
+- [ ] Source links if any claim is non-obvious or recent
+
+If any are missing, the reply is incomplete.
+
+---
+
+# PART 7: ERROR PROTOCOL
+
+If you were wrong, respond with this exact structure:
+
+```
+STATEMENT OF ERROR: <what was wrong>
+ROOT CAUSE: <why it happened>
+CORRECTED INSTRUCTION: <what to do instead>
+PREVENTION: <safeguard adopted now>
+```
+
+Then deliver the corrected asset.
+
+---
+
+# PART 8: CONTROL WORDS
+
+The operator may type these as commands. Respond exactly as specified.
+
+| Word | Action |
+|---|---|
+| **REFOCUS** | Reply: "Hard reset executed. State the core objective." Wait for input. |
+| **CONTINUE** | Send the next queued section of a multi-part reply. |
+| **COMPACT** | Shorten output. Keep all steps. Strip explanation. |
+| **EXPAND** | Add detail and edge cases to the previous reply. |
+| **DRY RUN** | Show exactly what would happen. Make no changes. |
+
+---
+
+# PART 9: CLARIFIERS PROTOCOL
+
+- Bundle all clarifiers ONCE at the top when needed.
+- Only ask for variables you cannot safely assume: credentials, undisclosed file paths, exact app versions, budget caps, private API keys, target account names, destructive actions.
+- Use compact format with example answers.
+- Otherwise proceed with smart defaults and state which defaults you used.
+- Maximum 5 clarifiers ever. If you need more, you don't have enough context: stop and ask the operator to brief you.
+
+---
+
+# PART 10: RESEARCH AND CITATIONS
+
+- Browse for anything time-volatile or niche.
+- Cite sources inline. Prefer official docs, standards, primary data.
+- Distinguish FACT vs INFERENCE explicitly when relevant.
+- If claims could have changed recently, verify before advising.
+
+---
+
+# PART 11: MULTI-MESSAGE RESPONSES
+
+If the best answer needs multiple messages, end the reply with:
+
+```
+STOP. Reply CONTINUE for more.
+```
+
+Never silently truncate.
+
+---
+
+# PART 12: DEFAULTS (OVERRIDABLE)
+
+- **OS:** macOS Sequoia or later
+- **Browser:** Safari and Chrome, current versions
+- **Mobile:** iOS / iPadOS current
+- **Editor:** TextEdit, or VS Code for code
+- **Local data folder:** `/Users/Shared/Projects/` unless the operator specifies otherwise
+- **Risk posture:** safe and reversible first. Destructive only with explicit confirm.
+- **Units:** USD, sq ft, gallons, miles, 12-hour time
+
+---
+
+# PART 13: PROJECT METADATA
+
+> Filled by `/bootstrap`. Edit if facts change.
+
+- **Name:** {{PROJECT_NAME}}
+- **Purpose:** {{PROJECT_PURPOSE_ONE_SENTENCE}}
+- **Owner / client:** {{OWNER_OR_CLIENT}}
+- **Live URL:** {{LIVE_URL_OR_TBD}}
+- **Repo path:** {{LOCAL_PATH}}
+- **Deploy target:** {{DEPLOY_TARGET}}
+
+---
+
+# PART 14: STACK
+
+- **Language:** {{LANGUAGE}}
+- **Framework:** {{FRAMEWORK}}
+- **Database:** {{DATABASE}}
+- **Hosting:** {{HOSTING}}
+- **Package manager:** {{NPM_PNPM_YARN_OR_OTHER}}
+- **Other key services:** {{LIST}}
+
+Detailed file map: `docs/ARCHITECTURE.md`.
+
+---
+
+# PART 15: COMMON COMMANDS
+
+```bash
+# Install deps
+{{INSTALL_CMD}}
+
+# Dev server
+{{DEV_CMD}}
+
+# Build
+{{BUILD_CMD}}
+
+# Test
+{{TEST_CMD}}
+
+# Type check / lint
+{{TYPECHECK_CMD}}
+
+# Deploy
+{{DEPLOY_CMD}}
+```
+
+---
+
+# PART 16: PROJECT-SPECIFIC CONVENTIONS
+
+> Things unique to THIS repo. Filled by `/bootstrap` or as discovered.
+
+- Operator materials live in `{{INPUTS_PATH}}`. Read `{{INPUTS_PATH}}README.md` for the layout. If `{{INPUTS_PATH}}INGEST_MANIFEST.md` exists, read it before starting work.
+- {{CONVENTION_1}}
+- {{CONVENTION_2}}
+- {{CONVENTION_3}}
+
+---
+
+# PART 17: DON'T TOUCH
+
+> Paths the agent must never modify without explicit instruction from the operator.
+
+- `.env`, `.env.local`, `.env.production`, any secret files
+- `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` (let the package manager regen)
+- `.git/` internals
+- {{OTHER_PROTECTED_PATHS}}
+
+---
+
+# PART 18: WHERE TO LOOK
+
+| Need | File |
+|---|---|
+| Where am I right now | `HANDOFF.md` |
+| What's blocking | `docs/MANUAL_TASKS.md` |
+| What we're prioritizing | `docs/PROJECT_STATE.md` |
+| What happened recently | `docs/SESSION_NOTES.md` |
+| Stack and file map | `docs/ARCHITECTURE.md` |
+| How to behave | `CLAUDE.md` (this file) |

package/templates/HANDOFF.md

@@ -0,0 +1,49 @@
+# HANDOFF.md
+
+> **READ THIS FIRST.** Single page. Current state only. Overwritten by `/prompt-end` every session.
+
+## Where we are right now
+
+**Status:** {{ONE_LINE_CURRENT_STATE}}
+**Last session ended:** {{YYYY-MM-DD_HH:MM}}
+**Branch:** {{CURRENT_BRANCH}}
+**Working tree:** {{CLEAN_OR_DIRTY_FILE_COUNT}}
+
+## What to do next
+
+The very next action when the operator opens a session:
+
+1. {{NEXT_ACTION_STEP_1}}
+2. {{NEXT_ACTION_STEP_2}}
+3. {{NEXT_ACTION_STEP_3}}
+
+## Active context
+
+**Current objective:** {{WHAT_WE_ARE_BUILDING_OR_FIXING}}
+
+**In progress:**
+- {{TASK}}: {{STATUS}}
+
+**Blocked on:**
+- {{BLOCKER_OR_NONE}}
+
+**Decisions pending operator input:**
+- {{QUESTION_OR_NONE}}
+
+## Files I touched last session
+
+- {{PATH}}: {{WHY}}
+- {{PATH}}: {{WHY}}
+
+## Don't forget
+
+- {{IMPORTANT_REMINDER_OR_NONE}}
+
+## Safe to skip if you read this
+
+- `docs/SESSION_NOTES.md` (full history): only read if you need to know how we got here
+- `docs/PROJECT_STATE.md` (priorities): only read if context here feels stale
+
+---
+
+*Generated by `/prompt-end`. To regenerate from scratch, run `/bootstrap`.*

package/templates/README.md

@@ -0,0 +1,15 @@
+# {{PROJECT_NAME}}
+
+{{PROJECT_PURPOSE_ONE_SENTENCE}}
+
+## Owner
+
+{{OWNER_OR_CLIENT}}
+
+## Deploy target
+
+{{LIVE_URL_OR_TBD}}
+
+## Working with the agent
+
+Open Claude Code and run `/prompt-start` to brief the agent on current state. See `CLAUDE.md` for the full operating manual.

package/templates/_gitignore

@@ -0,0 +1,9 @@
+node_modules/
+.DS_Store
+.env
+.env.local
+*.log
+dist/
+build/
+.next/
+coverage/

package/templates/docs/ARCHITECTURE.md

@@ -0,0 +1,59 @@
+# ARCHITECTURE.md
+
+> Stack details, file map, deploy pipeline. Reference doc.
+> Filled by `/bootstrap`. Updated when stack changes.
+
+## Stack
+
+| Layer | Tech | Version |
+|---|---|---|
+| Language | {{LANGUAGE}} | {{VERSION}} |
+| Framework | {{FRAMEWORK}} | {{VERSION}} |
+| Database | {{DATABASE}} | {{VERSION}} |
+| Auth | {{AUTH}} | - |
+| Hosting | {{HOSTING}} | - |
+| CDN | {{CDN}} | - |
+| Email | {{EMAIL_SERVICE}} | - |
+| Analytics | {{ANALYTICS}} | - |
+| Payments | {{PAYMENTS}} | - |
+| Other | {{OTHER}} | - |
+
+## File map
+
+```
+{{REPO_NAME}}/
+├── {{DIR_1}}/         # {{WHAT_LIVES_HERE}}
+├── {{DIR_2}}/         # {{WHAT_LIVES_HERE}}
+└── {{DIR_3}}/         # {{WHAT_LIVES_HERE}}
+```
+
+## Environment variables
+
+> Names only. Never paste secrets here.
+
+```
+{{ENV_VAR_1}}=        # purpose
+{{ENV_VAR_2}}=        # purpose
+{{ENV_VAR_3}}=        # purpose
+```
+
+Source of truth: `.env.local` (git-ignored). Template: `.env.example`.
+
+## Deploy
+
+- **Production:** {{PROD_DEPLOY_HOW}}
+- **Staging:** {{STAGING_OR_NONE}}
+- **Trigger:** {{AUTO_OR_MANUAL}}
+- **Domain DNS:** {{WHERE_DNS_LIVES}}
+
+## External services
+
+| Service | What it does | Where credentials live |
+|---|---|---|
+| {{SERVICE_1}} | {{PURPOSE}} | {{1Password / .env / dashboard}} |
+| {{SERVICE_2}} | {{PURPOSE}} | {{LOCATION}} |
+
+## Known gotchas
+
+- {{GOTCHA_1}}
+- {{GOTCHA_2}}

package/templates/docs/MANUAL_TASKS.md

@@ -0,0 +1,20 @@
+# MANUAL_TASKS.md
+
+> Tasks the agent **cannot** do. The operator must do these manually.
+> Examples: paying for a service, entering a password, DNS changes, physical actions, account creation behind 2FA.
+
+## Active
+
+<!-- Format:
+- [ ] <task>, needed because <reason>, added <YYYY-MM-DD>
+-->
+
+## Done
+
+<!-- Move completed items here with completion date -->
+
+## Notes
+
+- Agent appends to "Active" via `/prompt-end` when it hits a wall.
+- The operator checks this file before each session and clears what's done.
+- If a task has been Active for >7 days, escalate or remove.

package/templates/docs/PROJECT_STATE.md

@@ -0,0 +1,41 @@
+# PROJECT_STATE.md
+
+> Rolling snapshot of where the project is right now.
+> Updated by `/prompt-end` when architecture or priorities change.
+> Source of truth for "what are we working on."
+
+## Status
+
+- **Phase:** {{PHASE}}  <!-- e.g. "Pre-launch", "MVP shipping", "Maintenance" -->
+- **Last shipped:** {{LAST_SHIP_DATE_AND_FEATURE}}
+- **Current branch:** {{BRANCH}}
+- **Live URL health:** {{HEALTHY_OR_ISSUES}}
+
+## Top 3 priorities
+
+1. {{P1}}
+2. {{P2}}
+3. {{P3}}
+
+## In progress
+
+- {{ACTIVE_TASK_1}}, owner: agent, eta: {{ETA}}
+- {{ACTIVE_TASK_2}}, owner: operator, eta: {{ETA}}
+
+## Recently done
+
+- {{DONE_1}}
+- {{DONE_2}}
+
+## Blockers
+
+- {{BLOCKER_OR_NONE}}
+
+## Key paths
+
+- {{IMPORTANT_FILE_OR_DIR_1}}: {{WHY_IT_MATTERS}}
+- {{IMPORTANT_FILE_OR_DIR_2}}: {{WHY_IT_MATTERS}}
+
+## Open questions for the operator
+
+- {{QUESTION_OR_NONE}}

package/templates/docs/SESSION_NOTES.md

@@ -0,0 +1,29 @@
+# SESSION_NOTES.md
+
+> Append-only log. Newest entry on top.
+> Written by `/prompt-end` at session close.
+> Read by `/prompt-start` (last 50 lines) at session open.
+
+<!-- Entry format:
+
+## YYYY-MM-DD HH:MM  Session title
+
+**Objective:** <what the operator asked for>
+
+**Done:**
+- <deliverable>
+
+**Files changed:**
+- <path>: <reason>
+
+**Decisions made:**
+- <decision and why>
+
+**Open threads:**
+- <thing left unfinished>
+
+**Next session should:**
+- <specific next action>
+
+---
+-->

package/templates/inputs/README.md

@@ -0,0 +1,25 @@
+# inputs/
+
+This folder is for material you bring into the project: research, reference repos, brand images, scratch notes, anything you want the agent to read but that is not application code.
+
+## What goes where
+
+| Subfolder | What to drop here |
+|---|---|
+| `research/` | PDFs, articles, notes, transcripts, exported websites |
+| `references/` | Cloned repos or code samples worth quoting |
+| `images/` | Brand assets, mockups, screenshots, photos |
+| `notes/` | Free-form scratch notes, voice memos transcribed, ideas |
+| (root)    | Loose files that do not fit a subfolder |
+
+## Is this folder tracked by git?
+
+No, by default. The repo's `.gitignore` excludes everything in `{{INPUTS_PATH}}` except this `README.md`. If you want a particular file committed, edit `.gitignore` and weaken the `inputs/` rule, then `git add <path>`.
+
+## Manifest
+
+If you scaffolded with `ostup init --ingest <path>` (or answered "yes" to the materials prompt), an `INGEST_MANIFEST.md` will be next to this file listing what was copied in.
+
+## Telling agents about new material
+
+Drop files in. Tell the agent: "Read `{{INPUTS_PATH}}`." That is enough. The agent has been pre-instructed via `CLAUDE.md` to look here.