@oaklandzoo/ostup 0.1.0

package/templates/.claude/commands/create-prd.md

@@ -0,0 +1,85 @@
+---
+description: Draft a PRD for a new feature. Asks 3-5 clarifying questions, then writes /tasks/prd-[feature-name].md.
+---
+
+# Rule: Generating a Product Requirements Document (PRD)
+
+## Goal
+
+To guide an AI assistant in creating a detailed Product Requirements Document (PRD) in Markdown format, based on an initial user prompt. The PRD should be clear, actionable, and suitable for a junior developer to understand and implement the feature.
+
+## Process
+
+1.  **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality.
+2.  **Ask Clarifying Questions:** Before writing the PRD, the AI *must* ask only the most essential clarifying questions needed to write a clear PRD. Limit questions to 3-5 critical gaps in understanding. The goal is to understand the "what" and "why" of the feature, not necessarily the "how" (which the developer will figure out). Make sure to provide options in letter/number lists so I can respond easily with my selections.
+3.  **Generate PRD:** Based on the initial prompt and the user's answers to the clarifying questions, generate a PRD using the structure outlined below.
+4.  **Save PRD:** Save the generated document as `prd-[feature-name].md` inside the `/tasks` directory.
+
+## Clarifying Questions (Guidelines)
+
+Ask only the most critical questions needed to write a clear PRD. Focus on areas where the initial prompt is ambiguous or missing essential context. Common areas that may need clarification:
+
+*   **Problem/Goal:** If unclear - "What problem does this feature solve for the user?"
+*   **Core Functionality:** If vague - "What are the key actions a user should be able to perform?"
+*   **Scope/Boundaries:** If broad - "Are there any specific things this feature *should not* do?"
+*   **Success Criteria:** If unstated - "How will we know when this feature is successfully implemented?"
+
+**Important:** Only ask questions when the answer isn't reasonably inferable from the initial prompt. Prioritize questions that would significantly impact the PRD's clarity.
+
+### Formatting Requirements
+
+- **Number all questions** (1, 2, 3, etc.)
+- **List options for each question as A, B, C, D, etc.** for easy reference
+- Make it simple for the user to respond with selections like "1A, 2C, 3B"
+
+### Example Format
+
+```
+1. What is the primary goal of this feature?
+   A. Improve user onboarding experience
+   B. Increase user retention
+   C. Reduce support burden
+   D. Generate additional revenue
+
+2. Who is the target user for this feature?
+   A. New users only
+   B. Existing users only
+   C. All users
+   D. Admin users only
+
+3. What is the expected timeline for this feature?
+   A. Urgent (1-2 weeks)
+   B. High priority (3-4 weeks)
+   C. Standard (1-2 months)
+   D. Future consideration (3+ months)
+```
+
+## PRD Structure
+
+The generated PRD should include the following sections:
+
+1.  **Introduction/Overview:** Briefly describe the feature and the problem it solves. State the goal.
+2.  **Goals:** List the specific, measurable objectives for this feature.
+3.  **User Stories:** Detail the user narratives describing feature usage and benefits.
+4.  **Functional Requirements:** List the specific functionalities the feature must have. Use clear, concise language (e.g., "The system must allow users to upload a profile picture."). Number these requirements.
+5.  **Non-Goals (Out of Scope):** Clearly state what this feature will *not* include to manage scope.
+6.  **Design Considerations (Optional):** Link to mockups, describe UI/UX requirements, or mention relevant components/styles if applicable.
+7.  **Technical Considerations (Optional):** Mention any known technical constraints, dependencies, or suggestions (e.g., "Should integrate with the existing Auth module").
+8.  **Success Metrics:** How will the success of this feature be measured? (e.g., "Increase user engagement by 10%", "Reduce support tickets related to X").
+9.  **Open Questions:** List any remaining questions or areas needing further clarification.
+
+## Target Audience
+
+Assume the primary reader of the PRD is a **junior developer**. Therefore, requirements should be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the feature's purpose and core logic.
+
+## Output
+
+*   **Format:** Markdown (`.md`)
+*   **Location:** `/tasks/`
+*   **Filename:** `prd-[feature-name].md`
+
+## Final instructions
+
+1. Do NOT start implementing the PRD
+2. Make sure to ask the user clarifying questions
+3. Take the user's answers to the clarifying questions and improve the PRD

package/templates/.claude/commands/generate-tasks.md

@@ -0,0 +1,74 @@
+---
+description: Generate a stepwise task list from a PRD or requirements. Two-phase: parent tasks first, then sub-tasks after "Go".
+---
+
+# Rule: Generating a Task List from User Requirements
+
+## Goal
+
+To guide an AI assistant in creating a detailed, step-by-step task list in Markdown format based on user requirements, feature requests, or existing documentation. The task list should guide a developer through implementation.
+
+## Output
+
+- **Format:** Markdown (`.md`)
+- **Location:** `/tasks/`
+- **Filename:** `tasks-[feature-name].md` (e.g., `tasks-user-profile-editing.md`)
+
+## Process
+
+1.  **Receive Requirements:** The user provides a feature request, task description, or points to existing documentation
+2.  **Analyze Requirements:** The AI analyzes the functional requirements, user needs, and implementation scope from the provided information
+3.  **Phase 1: Generate Parent Tasks:** Based on the requirements analysis, create the file and generate the main, high-level tasks required to implement the feature. **IMPORTANT: Always include task 0.0 "Create feature branch" as the first task, unless the user specifically requests not to create a branch.** Use your judgement on how many additional high-level tasks to use. It's likely to be about 5. Present these tasks to the user in the specified format (without sub-tasks yet). Inform the user: "I have generated the high-level tasks based on your requirements. Ready to generate the sub-tasks? Respond with 'Go' to proceed."
+4.  **Wait for Confirmation:** Pause and wait for the user to respond with "Go".
+5.  **Phase 2: Generate Sub-Tasks:** Once the user confirms, break down each parent task into smaller, actionable sub-tasks necessary to complete the parent task. Ensure sub-tasks logically follow from the parent task and cover the implementation details implied by the requirements.
+6.  **Identify Relevant Files:** Based on the tasks and requirements, identify potential files that will need to be created or modified. List these under the `Relevant Files` section, including corresponding test files if applicable.
+7.  **Generate Final Output:** Combine the parent tasks, sub-tasks, relevant files, and notes into the final Markdown structure.
+8.  **Save Task List:** Save the generated document in the `/tasks/` directory with the filename `tasks-[feature-name].md`, where `[feature-name]` describes the main feature or task being implemented (e.g., if the request was about user profile editing, the output is `tasks-user-profile-editing.md`).
+
+## Output Format
+
+The generated task list _must_ follow this structure:
+
+```markdown
+## Relevant Files
+
+- `path/to/potential/file1.ts` - Brief description of why this file is relevant (e.g., Contains the main component for this feature).
+- `path/to/file1.test.ts` - Unit tests for `file1.ts`.
+- `path/to/another/file.tsx` - Brief description (e.g., API route handler for data submission).
+- `path/to/another/file.test.tsx` - Unit tests for `another/file.tsx`.
+- `lib/utils/helpers.ts` - Brief description (e.g., Utility functions needed for calculations).
+- `lib/utils/helpers.test.ts` - Unit tests for `helpers.ts`.
+
+### Notes
+
+- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory).
+- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration.
+
+## Instructions for Completing Tasks
+
+**IMPORTANT:** As you complete each task, you must check it off in this markdown file by changing `- [ ]` to `- [x]`. This helps track progress and ensures you don't skip any steps.
+
+Example:
+- `- [ ] 1.1 Read file` → `- [x] 1.1 Read file` (after completing)
+
+Update the file after completing each sub-task, not just after completing an entire parent task.
+
+## Tasks
+
+- [ ] 0.0 Create feature branch
+  - [ ] 0.1 Create and checkout a new branch for this feature (e.g., `git checkout -b feature/[feature-name]`)
+- [ ] 1.0 Parent Task Title
+  - [ ] 1.1 [Sub-task description 1.1]
+  - [ ] 1.2 [Sub-task description 1.2]
+- [ ] 2.0 Parent Task Title
+  - [ ] 2.1 [Sub-task description 2.1]
+- [ ] 3.0 Parent Task Title (may not require sub-tasks if purely structural or configuration)
+```
+
+## Interaction Model
+
+The process explicitly requires a pause after generating parent tasks to get user confirmation ("Go") before proceeding to generate the detailed sub-tasks. This ensures the high-level plan aligns with user expectations before diving into details.
+
+## Target Audience
+
+Assume the primary reader of the task list is a **junior developer** who will implement the feature.

package/templates/.claude/commands/prompt-end.md

@@ -0,0 +1,129 @@
+---
+description: Close session. Rewrite HANDOFF.md. Append to SESSION_NOTES.md. Update other docs only if changed.
+---
+
+# Session close
+
+Execute in order. Do not skip.
+
+## Step 1: Verify all claimed deliverables exist
+
+```bash
+git status --short
+git diff --stat
+```
+
+For every file you claimed to create or edit this session, confirm it exists with `ls` or `wc -l`. If anything is missing, declare error per CLAUDE.md Part 7 before continuing. Do not write a clean handoff over a dirty session.
+
+## Step 2: REWRITE HANDOFF.md (overwrite, not append)
+
+`HANDOFF.md` is a single-page snapshot. Replace its contents entirely with the current state. Use this template:
+
+```markdown
+# 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 | N dirty files>
+
+## What to do next
+
+The very next action when the operator opens a session:
+
+1. <next action 1>
+2. <next action 2>
+3. <next action 3>
+
+## Active context
+
+**Current objective:** <what we are building or fixing>
+
+**In progress:**
+- <task>: <status>
+
+**Blocked on:**
+- <blocker or "none">
+
+**Decisions pending the operator input:**
+- <question or "none">
+
+## Files I touched last session
+
+- <path>: <why>
+
+## Don't forget
+
+- <important reminder or "none">
+```
+
+Save with: `cat > HANDOFF.md << 'EOF' ... EOF` or equivalent. Verify with `cat HANDOFF.md` after writing.
+
+## Step 3: Append to docs/SESSION_NOTES.md
+
+Add a new entry at the TOP of the file (newest first):
+
+```markdown
+## 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:**
+- <unfinished item>
+
+**Next session should:**
+- <specific action>
+
+---
+```
+
+## Step 4: Update docs/PROJECT_STATE.md ONLY IF priorities changed
+
+Skip if priorities are identical to before. Don't churn this file.
+
+## Step 5: Update docs/MANUAL_TASKS.md if you hit a wall
+
+Append any new human-only blockers:
+
+```markdown
+- [ ] <task>, needed because <reason>, added <YYYY-MM-DD>
+```
+
+## Step 6: Print the close-out
+
+```
+SESSION CLOSED
+
+Files updated:
+- HANDOFF.md            (rewritten)
+- docs/SESSION_NOTES.md (new entry appended)
+- docs/PROJECT_STATE.md (touched: yes/no)
+- docs/MANUAL_TASKS.md  (touched: yes/no)
+
+Files changed in repo:
+<git diff --stat output>
+
+Commit suggestion:
+git add -A
+git commit -m "<short summary of session>"
+
+Next session: run /prompt-start. First action will be:
+<first item from new HANDOFF.md>
+```
+
+Do NOT run the commit yourself unless the operator explicitly says so.
+
+Stop.

package/templates/.claude/commands/prompt-mid.md

@@ -0,0 +1,74 @@
+---
+description: Mid-session refocus. Check context budget, verify progress, restate plan.
+---
+
+# Mid-session check
+
+Execute in order.
+
+## Step 1: Context budget
+
+Estimate context used so far. If >80% used, alert the operator immediately:
+
+```
+WARNING: Context at <X>%. Approaching limit.
+Recommend: /prompt-end now and start fresh session.
+```
+
+If under 80%, continue.
+
+## Step 2: Restate where we are
+
+Print:
+
+```
+MID-SESSION CHECKPOINT
+
+Original objective: <what the operator said at /prompt-start>
+
+Done so far:
+- <bullet 1>
+- <bullet 2>
+
+In progress:
+- <current task>
+
+Blocked on:
+- <list, or "nothing">
+```
+
+## Step 3: Verify, do not assume
+
+For every file you claim to have created or edited in this session:
+
+```bash
+ls -la <file_path>
+wc -l <file_path>
+```
+
+If a file you claimed to write does not exist, declare an error per CLAUDE.md error protocol:
+
+```
+STATEMENT OF ERROR: I claimed <file> was created. It does not exist.
+ROOT CAUSE: <why>
+CORRECTED INSTRUCTION: <what I'll do now>
+PREVENTION: <how I'll avoid this next time>
+```
+
+## Step 4: Loop detection
+
+If you have tried to fix the same bug 3+ times without progress, stop and print:
+
+```
+LOOP DETECTED on: <issue>
+Attempts: <count>
+Recommend: the operator manually inspect, or change approach.
+```
+
+## Step 5: Confirm next step
+
+```
+Continue with <next step>? Or pivot?
+```
+
+Wait for confirmation before proceeding.

package/templates/.claude/commands/prompt-start.md

@@ -0,0 +1,85 @@
+---
+description: Open a working session. Read HANDOFF, state where we are, ask for objective.
+---
+
+# Session start
+
+Execute these steps in order. Do not ask the operator anything until Step 7.
+
+## Step 1: Confirm rules are loaded
+
+```bash
+cat CLAUDE.md
+```
+
+You must internalize Parts 3 (Hard Rules), 4 (Reply Format), 5 (Style), 6 (Done), and 7 (Error Protocol) before proceeding.
+
+## Step 2: Read HANDOFF first
+
+```bash
+cat HANDOFF.md
+```
+
+This tells you where the last session ended and what comes next. It is the entry point.
+
+## Step 3: Check blockers
+
+```bash
+cat docs/MANUAL_TASKS.md
+```
+
+If there are active items, surface them. Some may block today's work.
+
+## Step 4: Working tree check
+
+```bash
+git status --short
+git branch --show-current
+git log --oneline -3
+```
+
+Note: dirty file count, current branch, last 3 commits.
+
+## Step 5: Optional sanity check
+
+If `CLAUDE.md` Part 15 lists a build or typecheck command, run it. Surface any failure before proceeding. Skip if no command defined.
+
+## Step 6: Print the briefing
+
+```
+SESSION OPEN
+
+Project: <from CLAUDE.md Part 13>
+Branch: <current>
+Working tree: <clean | N dirty files>
+
+WHERE WE ARE (from HANDOFF.md):
+<one-line status>
+
+LAST SESSION ENDED AT:
+<HANDOFF.md "Last session ended" timestamp>
+
+NEXT ACTIONS QUEUED (from HANDOFF.md):
+1. <action 1>
+2. <action 2>
+3. <action 3>
+
+ACTIVE BLOCKERS (from MANUAL_TASKS.md):
+- <blocker or "none">
+
+GUARDRAILS ACTIVE
+- Never claim done without testing
+- Verify files exist before referencing
+- No assuming, no training data: read current source
+- Alert at 20% context
+- Deliver downloadable files
+- Destructive ops require explicit confirm
+```
+
+## Step 7: Ask the operator
+
+```
+Proceed with queued actions, or different objective?
+```
+
+Wait for response before doing anything else.

package/templates/.ostup-config.yml.example

@@ -0,0 +1,10 @@
+# Sample .ostup-config.yml. Rename or copy to `.ostup-config.yml` to drive
+# non-interactive scaffolding via `ostup init --yes`.
+#
+# Precedence: CLI flags > this file > interactive prompts > defaults / TBD.
+
+projectName: my-app                              # used for PROJECT_NAME and REPO_NAME tokens
+purpose: A friendly thing that does X for Y      # one-sentence description (fills PURPOSE / WHAT_WE_ARE_BUILDING_OR_FIXING / WHAT_LIVES_HERE)
+owner: Mr. Goodshin                              # OWNER_OR_CLIENT
+stack: Next.js + Supabase + Vercel               # LANGUAGE / FRAMEWORK
+deploy: https://my-app.example.com               # DEPLOY_TARGET / LIVE_URL_OR_TBD (leave blank for TBD)

package/templates/AGENTS.md

@@ -0,0 +1,33 @@
+# Agents
+
+This repo is set up to be driven by AI coding agents through the Ostup Agent Kit.
+
+## Quick links
+
+- Repo: {{REPO_URL}}
+- Deploy: {{DEPLOY_URL}}
+
+## Project facts
+
+- Name: {{PROJECT_NAME}}
+- Owner: {{OWNER_OR_CLIENT}}
+- Stack: {{FRAMEWORK}}
+- Purpose: {{PROJECT_PURPOSE_ONE_SENTENCE}}
+
+## Materials
+
+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.
+
+## How to work with this repo
+
+1. Open Claude Code from the repo root.
+2. Run `/prompt-start` to brief the agent on current state.
+3. Read `CLAUDE.md` for the full operating manual.
+4. Read `HANDOFF.md` to see where the last session left off.
+
+## Slash commands available
+
+- `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`
+- `/create-prd`, `/generate-tasks`
+
+See each file under `.claude/commands/` for details.