@oaklandzoo/ostup 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/templates/START_HERE.md +92 -19
package/package.json
CHANGED
package/templates/START_HERE.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
# Start here
|
|
2
2
|
|
|
3
|
-
You just scaffolded **{{DISPLAY_NAME}}** with ostup. This file
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## First session, two steps
|
|
6
|
+
|
|
7
|
+
### 1. Open this folder in your CLI agent
|
|
6
8
|
|
|
7
9
|
In Terminal, from inside this folder:
|
|
8
10
|
|
|
@@ -10,32 +12,103 @@ In Terminal, from inside this folder:
|
|
|
10
12
|
claude
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
Or use `codex`, `gemini`, or whichever CLI agent you prefer.
|
|
16
|
+
|
|
17
|
+
### 2. Paste this as your first message
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
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.
|
|
21
|
+
|
|
22
|
+
After I approve, run /bootstrap to fill in this project's metadata, then start building.
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
That is the whole jump-in. The agent reads, asks, proposes, you approve, it builds.
|
|
26
|
+
|
|
27
|
+
## What got scaffolded
|
|
28
|
+
|
|
29
|
+
| File | Purpose | Who reads it |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| `START_HERE.md` | This file. Operator orientation. | You |
|
|
32
|
+
| `CLAUDE.md` | Agent rules: hard rules, reply format, style. | Agent |
|
|
33
|
+
| `AGENTS.md` | Quick project facts and kit cross-reference. | Agent |
|
|
34
|
+
| `HANDOFF.md` | Current session state. Rewritten at every session end. | Both |
|
|
35
|
+
| `docs/PROJECT_STATE.md` | Phase, priorities, key paths. | Agent |
|
|
36
|
+
| `docs/MANUAL_TASKS.md` | Tasks only you can do (paid, 2FA, physical). | Agent |
|
|
37
|
+
| `docs/SESSION_NOTES.md` | Append-only log of past sessions. | Both |
|
|
38
|
+
| `docs/ARCHITECTURE.md` | Stack, file map, env vars, deploy details. | Agent |
|
|
39
|
+
| `{{INPUTS_PATH}}` | Your source materials. May be empty. You can add files anytime. | Both |
|
|
40
|
+
| `tasks/` | PRDs and task lists for features. | Both |
|
|
41
|
+
| `.claude/commands/` | Slash command definitions. | Agent |
|
|
42
|
+
|
|
43
|
+
## Slash commands
|
|
44
|
+
|
|
45
|
+
Type these in your CLI agent. Each runs a structured routine.
|
|
46
|
+
|
|
47
|
+
| Command | What it does | When to run it |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| `/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. |
|
|
50
|
+
| `/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. |
|
|
51
|
+
| `/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. |
|
|
52
|
+
| `/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. |
|
|
53
|
+
| `/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. |
|
|
54
|
+
| `/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. |
|
|
55
|
+
|
|
56
|
+
## Three workflows
|
|
57
|
+
|
|
58
|
+
### A. First session (scope + start building)
|
|
59
|
+
|
|
60
|
+
1. `claude` in this folder.
|
|
61
|
+
2. Paste the prompt from step 2 above.
|
|
62
|
+
3. The agent reads everything, asks 2 or 3 questions, proposes an MVP.
|
|
63
|
+
4. You approve (or refine).
|
|
64
|
+
5. The agent runs `/bootstrap` to fill in project metadata.
|
|
65
|
+
6. The agent builds the first cut and pushes commits.
|
|
66
|
+
7. `/prompt-end` when you stop.
|
|
67
|
+
|
|
68
|
+
Works the same whether `{{INPUTS_PATH}}` is empty or full. With materials, the agent uses them. Without, it asks you what to build outright.
|
|
69
|
+
|
|
70
|
+
### B. Return session (pick up where you left off)
|
|
71
|
+
|
|
72
|
+
1. `claude` in this folder.
|
|
73
|
+
2. `/prompt-start`.
|
|
74
|
+
3. Approve the queued actions, or give a new objective.
|
|
75
|
+
4. Work.
|
|
76
|
+
5. `/prompt-end`.
|
|
14
77
|
|
|
15
|
-
|
|
78
|
+
### C. Build a new feature
|
|
16
79
|
|
|
17
|
-
|
|
80
|
+
1. `/create-prd` (the agent asks what, why, success criteria).
|
|
81
|
+
2. `/generate-tasks` (the agent breaks the PRD into a phased task list).
|
|
82
|
+
3. Tell the agent "Start at task 1.1" (or similar).
|
|
83
|
+
4. `/prompt-end` when you stop.
|
|
18
84
|
|
|
19
|
-
|
|
85
|
+
## Adding source materials later
|
|
20
86
|
|
|
21
|
-
|
|
87
|
+
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."
|
|
22
88
|
|
|
23
|
-
|
|
89
|
+
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.
|
|
24
90
|
|
|
25
|
-
|
|
91
|
+
## Where to put what
|
|
26
92
|
|
|
27
|
-
|
|
93
|
+
| What | Where |
|
|
94
|
+
|---|---|
|
|
95
|
+
| Source materials, brand assets, reference repos | `{{INPUTS_PATH}}` |
|
|
96
|
+
| PRDs and task lists for new features | `tasks/` |
|
|
97
|
+
| Project-wide facts (stack, deploy, env vars) | `docs/ARCHITECTURE.md` |
|
|
98
|
+
| Things blocked on something only you can do | `docs/MANUAL_TASKS.md` |
|
|
99
|
+
| Project-specific agent rules | `CLAUDE.md` Part 16 |
|
|
28
100
|
|
|
29
|
-
##
|
|
101
|
+
## When something feels wrong
|
|
30
102
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
103
|
+
| Symptom | First move |
|
|
104
|
+
|---|---|
|
|
105
|
+
| Agent is taking the wrong approach | Type `REFOCUS`. Resets the agent and asks for the core objective. |
|
|
106
|
+
| Agent claims it did something but you are not sure | `/prompt-mid`. The agent verifies its own claims and admits gaps. |
|
|
107
|
+
| You came back after a week and have no idea where you left off | `/prompt-start`. Reads HANDOFF and briefs you. |
|
|
108
|
+
| Agent keeps repeating the same broken fix | Type "LOOP DETECTED on \<issue\>" and ask for a different approach. |
|
|
109
|
+
| Vercel deploy returns 401 | Open the Vercel dashboard, find this project, Settings, Deployment Protection, Disable. |
|
|
110
|
+
| You need to install or update something only you can do | The agent appends it to `docs/MANUAL_TASKS.md`. Clear it when done. |
|
|
38
111
|
|
|
39
112
|
## When you no longer need this file
|
|
40
113
|
|
|
41
|
-
Delete it. It is for
|
|
114
|
+
Delete it. It is for orientation only and has no effect on your app.
|