@oaklandzoo/ostup 0.1.0 → 0.1.2

package/README.md

@@ -54,32 +54,35 @@ through creating them when you reach that step.
 
 ## Install
 
-Two paths. Pick the one that matches how you got ostup.
-
-### Path A: from npm (after `ostup` is published)
+The fastest path:
 
 ```
-npx ostup init
+npx @oaklandzoo/ostup init
 ```
 
-That is the whole install. `npx` downloads ostup on first run.
+That is the whole install. `npx` downloads ostup on first run, nothing
+to install permanently.
+
+If you'd rather install it globally so the command is just `ostup`:
 
-As of right now, `ostup` is not yet published to npm. Use Path B below.
+```
+npm install -g @oaklandzoo/ostup
+ostup --version    # should print 0.1.0
+ostup init
+```
 
-### Path B: from source (today's path)
+### Alternate: install from source
 
-If you cloned or downloaded https://github.com/DubsFan/goodshin:
+If you cloned https://github.com/DubsFan/goodshin and want to run from
+your local checkout:
 
 ```
 cd /path/to/goodshin/ostup
-npm install     # downloads ostup's own dependencies
-npm link        # adds `ostup` to your PATH globally
-ostup --version # should print 0.1.0
+npm install
+npm link
+ostup --version
 ```
 
-After `npm link` you can run `ostup` from any folder. You only do this
-once per machine.
-
 ## Use
 
 In Terminal, navigate to the parent folder where you want the new

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffolds a new repo with the Ostup Agent Kit pre-installed: slash commands, doc templates, and a clean working state.",
   "type": "module",
   "bin": {

package/src/mvp-flow.mjs

@@ -57,14 +57,14 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
   await ensureFreshTarget(targetDir, flags.force);
   await mkdir(targetDir, { recursive: true });
 
+  await maybeScaffoldStack({ stack: answers.stack, projectName: answers.projectName, targetDir });
+
   await ingestMaterials({
     targetDir,
     ingestPath: answers.ingestPath,
     isDryRun: isDryRun(),
   });
 
-  await maybeScaffoldStack({ stack: answers.stack, projectName: answers.projectName, targetDir });
-
   const tokens = buildTokenMap({
     projectName: answers.projectName,
     displayName: answers.displayName,

package/src/summary.mjs

@@ -22,7 +22,10 @@ export function renderSummary({ targetDir, repoUrl, deployUrl, profile, projectN
   lines.push(
     `  Profile:     ${profile || 'goodshin'}`,
     '================================================',
-    `  Next: cd ${projectName} && claude`,
+    `  Next steps:`,
+    `    1. cd ${projectName}`,
+    `    2. claude    (or codex, gemini, your preferred CLI agent)`,
+    `    3. Open START_HERE.md and paste the prompt as your first message`,
     '================================================',
     ''
   );

package/src/templates.mjs

@@ -23,6 +23,7 @@ export const REGISTRY = [
   { src: '.claude/commands/generate-tasks.md', dest: '.claude/commands/generate-tasks.md' },
   { src: 'CLAUDE.md',                          dest: 'CLAUDE.md' },
   { src: 'AGENTS.md',                          dest: 'AGENTS.md' },
+  { src: 'START_HERE.md',                      dest: 'START_HERE.md' },
   { src: 'HANDOFF.md',                         dest: 'HANDOFF.md' },
   { src: 'docs/PROJECT_STATE.md',              dest: 'docs/PROJECT_STATE.md' },
   { src: 'docs/MANUAL_TASKS.md',               dest: 'docs/MANUAL_TASKS.md' },

package/templates/START_HERE.md

@@ -0,0 +1,114 @@
+# Start here
+
+You just scaffolded **{{DISPLAY_NAME}}** with ostup. This is your operator manual. Read once. Refer back as needed. Delete the file when you no longer need it.
+
+## First session, two steps
+
+### 1. Open this folder in your CLI agent
+
+In Terminal, from inside this folder:
+
+```
+claude
+```
+
+Or use `codex`, `gemini`, or whichever CLI agent you prefer.
+
+### 2. Paste this as your first message
+
+```
+Read CLAUDE.md, AGENTS.md, and everything in {{INPUTS_PATH}}. If {{INPUTS_PATH}} has source materials (research, reference repos, brand assets, notes), use them as context. If it is empty or only has a README, that is fine. Either way, ask me up to 3 clarifying questions about what I want to build. Then propose a 30 to 60 minute MVP scope as a numbered list. Do not write code until I approve the scope.
+
+After I approve, run /bootstrap to fill in this project's metadata, then start building.
+```
+
+That is the whole jump-in. The agent reads, asks, proposes, you approve, it builds.
+
+## What got scaffolded
+
+| File | Purpose | Who reads it |
+|---|---|---|
+| `START_HERE.md` | This file. Operator orientation. | You |
+| `CLAUDE.md` | Agent rules: hard rules, reply format, style. | Agent |
+| `AGENTS.md` | Quick project facts and kit cross-reference. | Agent |
+| `HANDOFF.md` | Current session state. Rewritten at every session end. | Both |
+| `docs/PROJECT_STATE.md` | Phase, priorities, key paths. | Agent |
+| `docs/MANUAL_TASKS.md` | Tasks only you can do (paid, 2FA, physical). | Agent |
+| `docs/SESSION_NOTES.md` | Append-only log of past sessions. | Both |
+| `docs/ARCHITECTURE.md` | Stack, file map, env vars, deploy details. | Agent |
+| `{{INPUTS_PATH}}` | Your source materials. May be empty. You can add files anytime. | Both |
+| `tasks/` | PRDs and task lists for features. | Both |
+| `.claude/commands/` | Slash command definitions. | Agent |
+
+## Slash commands
+
+Type these in your CLI agent. Each runs a structured routine.
+
+| Command | What it does | When to run it |
+|---|---|---|
+| `/bootstrap` | Scans the repo and asks up to 5 clarifiers, then fills in `CLAUDE.md` Parts 13 to 17 and `docs/ARCHITECTURE.md` with your project's real facts. | Once, on the first session. |
+| `/prompt-start` | Reads HANDOFF, MANUAL_TASKS, git status. Briefs the agent on the current state. Asks "Proceed or pivot?" | Start of every session after the first. |
+| `/prompt-mid` | Checks context budget, restates progress, verifies any files the agent claimed to write actually exist. | Mid-session, if you feel lost or the agent seems off-track. |
+| `/prompt-end` | Rewrites HANDOFF, appends to SESSION_NOTES, surfaces any new blockers to MANUAL_TASKS. | End of every session. Always. Without this the next session has no memory of what just happened. |
+| `/create-prd` | Asks 3 to 5 clarifying questions, then writes a PRD to `tasks/prd-<feature>.md`. | Before building a significant new feature. Optional for small changes. |
+| `/generate-tasks` | Reads a PRD, breaks it into a phased task list at `tasks/tasks-<feature>.md` (parent tasks first, then sub-tasks after you say "Go"). | After a PRD is approved, before the agent starts coding. |
+
+## Three workflows
+
+### A. First session (scope + start building)
+
+1. `claude` in this folder.
+2. Paste the prompt from step 2 above.
+3. The agent reads everything, asks 2 or 3 questions, proposes an MVP.
+4. You approve (or refine).
+5. The agent runs `/bootstrap` to fill in project metadata.
+6. The agent builds the first cut and pushes commits.
+7. `/prompt-end` when you stop.
+
+Works the same whether `{{INPUTS_PATH}}` is empty or full. With materials, the agent uses them. Without, it asks you what to build outright.
+
+### B. Return session (pick up where you left off)
+
+1. `claude` in this folder.
+2. `/prompt-start`.
+3. Approve the queued actions, or give a new objective.
+4. Work.
+5. `/prompt-end`.
+
+### C. Build a new feature
+
+1. `/create-prd` (the agent asks what, why, success criteria).
+2. `/generate-tasks` (the agent breaks the PRD into a phased task list).
+3. Tell the agent "Start at task 1.1" (or similar).
+4. `/prompt-end` when you stop.
+
+## Adding source materials later
+
+Drop files into `{{INPUTS_PATH}}` at any time: PDFs in `{{INPUTS_PATH}}research/`, code samples in `{{INPUTS_PATH}}references/`, images in `{{INPUTS_PATH}}images/`, scratch notes in `{{INPUTS_PATH}}notes/`. Then tell the agent: "I added new material in `{{INPUTS_PATH}}`, please re-read it."
+
+The folder is git-ignored by default so nothing leaks to your public repo unless you commit it explicitly. To commit a specific file, weaken the `inputs/` rule in `.gitignore` and `git add` the file.
+
+## Where to put what
+
+| What | Where |
+|---|---|
+| Source materials, brand assets, reference repos | `{{INPUTS_PATH}}` |
+| PRDs and task lists for new features | `tasks/` |
+| Project-wide facts (stack, deploy, env vars) | `docs/ARCHITECTURE.md` |
+| Things blocked on something only you can do | `docs/MANUAL_TASKS.md` |
+| Project-specific agent rules | `CLAUDE.md` Part 16 |
+
+## When something feels wrong
+
+| Symptom | First move |
+|---|---|
+| Agent is taking the wrong approach | Type `REFOCUS`. Resets the agent and asks for the core objective. |
+| Agent claims it did something but you are not sure | `/prompt-mid`. The agent verifies its own claims and admits gaps. |
+| You came back after a week and have no idea where you left off | `/prompt-start`. Reads HANDOFF and briefs you. |
+| Agent keeps repeating the same broken fix | Type "LOOP DETECTED on \<issue\>" and ask for a different approach. |
+| Vercel deploy returns 401 | Open the Vercel dashboard, find this project, Settings, Deployment Protection, Disable. |
+| You need to install or update something only you can do | The agent appends it to `docs/MANUAL_TASKS.md`. Clear it when done. |
+
+## When you no longer need this file
+
+Delete it. It is for orientation only and has no effect on your app.