Concrete guidance in New task>new instead of aphorisms; a test plan with every key
This commit is contained in:
Sam
@@ -180,3 +180,103 @@ Committed as `e44b0df`, documentation only — the running layout is untouched.
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-paperclip-2026-11-10-21-58-38|Rich discovery: .paperclip 2026-11-10 21:58:38]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclipai|.paperclip]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|.paperclip repository structure and configuration patterns]]
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Update (2026-11-10 22:15:52)
|
||||
|
||||
## Rich discovery update (2026-11-10 22:15:52)
|
||||
|
||||
The picker is built and driven end to end.
|
||||
|
||||
## Skills picker — `Agents>agents`, fifth tab
|
||||
|
||||
It reads the same source `pi-config` reads (`~/.agents/skills`), plus Paperclip's company list and the chosen agent's own list, and marks every row:
|
||||
|
||||
```
|
||||
Builder · space toggles the chosen skill
|
||||
▸ archify not in Paperclip
|
||||
caveman not in Paperclip
|
||||
nixos-workflow in Paperclip
|
||||
obsidian-cli in Paperclip
|
||||
project-docs in Paperclip
|
||||
```
|
||||
|
||||
Pressing space on a skill that Paperclip does not know copies it into the company managed folder, imports it, and assigns it **to this agent only**. Verified on `Builder`:
|
||||
|
||||
```
|
||||
before desiredSkills: ['paperclipai/paperclip/paperclip']
|
||||
space → 'local/556e0be78e/archify' added by Paperclip
|
||||
space → removed again; back to the original list
|
||||
```
|
||||
|
||||
That is the picker you asked for, and every step is a real call, not a plan.
|
||||
|
||||
## Extensions picker — sixth tab
|
||||
|
||||
Paperclip has no extension model, so the equivalent is the per-agent command. This tab lists `~/.agents/extensions`, and turning one on writes:
|
||||
|
||||
```
|
||||
~/.local/share/paperclip-harness/wrappers/<agentId>.sh
|
||||
#!/bin/sh
|
||||
exec pi --extension /home/sam/.agents/extensions/ask-user-question/index.ts "$@"
|
||||
```
|
||||
|
||||
and sets `adapterConfig.command` to that file — keeping the agent's model and folder untouched. Turning the last one off deletes the wrapper and puts the command back to plain `pi` (verified: `command: pi`, no wrapper file). A unit test pins write → read-back → remove, because a wrong wrapper would stop an agent from starting at all.
|
||||
|
||||
Two bugs found while testing: the wrapper reader mistook `…/ask-user-question/index.ts` for an extension called `index`, and the screen lagged a keystroke behind a reload. Both fixed.
|
||||
|
||||
## Junk TUIOS sessions — research and plan
|
||||
|
||||
`tuios ls --all-hosts` shows **37 sessions. 21 are from the closed project's tests**: `harness-demo-card-*` (18) and `office-test-1*` (3). The rest are yours and should stay — `office` (32 panes, attached), `paperclip-harness` (the layout), `factory`, and your personal ones.
|
||||
|
||||
**Nothing was killed.** That is destructive and the list is the evidence to decide on. Proposed, in `docs/SESSIONS.md`:
|
||||
|
||||
1. Kill the 21 by explicit pattern, with a `--dry-run` that only prints.
|
||||
2. A `bin/prune` that shows sessions by age and pane count, and refuses any attached session.
|
||||
3. A rule that every test script kills the session it creates — those 21 exist because creating was one command and cleaning up was not.
|
||||
4. Never prune `paperclip-harness`: its panes are the layout, rebuilt by `R`.
|
||||
|
||||
## Where to find a Pi session
|
||||
|
||||
```
|
||||
~/.pi/paperclips/<timestamp>-<agentId>.jsonl 178 files here
|
||||
GET /api/agents/{id}/task-sessions → task → session file + folder
|
||||
```
|
||||
|
||||
Open it with `pi --resume` (pick from Pi's list), or `pi --session <file>` for that exact conversation — the same flag Paperclip uses. Your instinct was right: the folder plus `--resume` is enough; a transcript tab is optional later.
|
||||
|
||||
## The test plan, as written earlier
|
||||
|
||||
1. Create a task in `New task>new` with a blocker and a verify command; see it in `Board>board`.
|
||||
2. Assign it in `Board>board`, then watch it in `Agents>agents` — roster, runs, its log.
|
||||
3. Let it finish; read the diff in `Work>work` and the verdict in `Work>review`.
|
||||
4. Merge with `bin/merge`; confirm the verify command passes on `main`.
|
||||
5. Open the dependent task and confirm it can now proceed.
|
||||
6. Press `R` in `Repair>repair` and confirm all eight workspaces return.
|
||||
7. Change an agent's model in `Agents>agents` settings and confirm it applies to the *next* run only.
|
||||
|
||||
All eight workspaces are running on the new build. Committed as `1f8731f`.
|
||||
|
||||
## Source paths observed
|
||||
|
||||
- `home/sam/.local/share/paperclip-harness/wrappers/403de1f7-645c-4d35-bc7e-19b01d77bacc.sh`
|
||||
- `paperclip-harness/tui/paperclip`
|
||||
- `home/sam/paseo/projects/paperclip-harness/docs/SESSIONS.md`
|
||||
- `paperclipai/paperclip/paperclip`
|
||||
- `local/556e0be78e/archify`
|
||||
- `.local/share/paperclip-harness/wrappers`
|
||||
- `home/sam/.agents/extensions/ask-user-question/index.ts`
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 84%
|
||||
- Reason: Update component/repository context with detailed discovered structure and configuration
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 22:15:52 -->
|
||||
|
||||
- session: [[packs/paperclip-harness/80-sessions/paperclip-harness-skills-extension-pickers-built-junk-tuios-|Paperclip harness: skills/extension pickers built, junk TUIOS session research, Pi session lookup]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-paperclipai-2026-11-10-22-15-52|Rich discovery: paperclipai 2026-11-10 22:15:52]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclipai|paperclipai]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|paperclipai repository structure and configuration patterns]]
|
||||
|
||||
@@ -1971,3 +1971,103 @@ Committed as `e44b0df`, documentation only — the running layout is untouched.
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-paperclip-2026-11-10-21-58-38|Rich discovery: .paperclip 2026-11-10 21:58:38]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclipai|.paperclip]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|.paperclip repository structure and configuration patterns]]
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Update (2026-11-10 22:15:52)
|
||||
|
||||
## Structural/configuration observations (2026-11-10 22:15:52)
|
||||
|
||||
The picker is built and driven end to end.
|
||||
|
||||
## Skills picker — `Agents>agents`, fifth tab
|
||||
|
||||
It reads the same source `pi-config` reads (`~/.agents/skills`), plus Paperclip's company list and the chosen agent's own list, and marks every row:
|
||||
|
||||
```
|
||||
Builder · space toggles the chosen skill
|
||||
▸ archify not in Paperclip
|
||||
caveman not in Paperclip
|
||||
nixos-workflow in Paperclip
|
||||
obsidian-cli in Paperclip
|
||||
project-docs in Paperclip
|
||||
```
|
||||
|
||||
Pressing space on a skill that Paperclip does not know copies it into the company managed folder, imports it, and assigns it **to this agent only**. Verified on `Builder`:
|
||||
|
||||
```
|
||||
before desiredSkills: ['paperclipai/paperclip/paperclip']
|
||||
space → 'local/556e0be78e/archify' added by Paperclip
|
||||
space → removed again; back to the original list
|
||||
```
|
||||
|
||||
That is the picker you asked for, and every step is a real call, not a plan.
|
||||
|
||||
## Extensions picker — sixth tab
|
||||
|
||||
Paperclip has no extension model, so the equivalent is the per-agent command. This tab lists `~/.agents/extensions`, and turning one on writes:
|
||||
|
||||
```
|
||||
~/.local/share/paperclip-harness/wrappers/<agentId>.sh
|
||||
#!/bin/sh
|
||||
exec pi --extension /home/sam/.agents/extensions/ask-user-question/index.ts "$@"
|
||||
```
|
||||
|
||||
and sets `adapterConfig.command` to that file — keeping the agent's model and folder untouched. Turning the last one off deletes the wrapper and puts the command back to plain `pi` (verified: `command: pi`, no wrapper file). A unit test pins write → read-back → remove, because a wrong wrapper would stop an agent from starting at all.
|
||||
|
||||
Two bugs found while testing: the wrapper reader mistook `…/ask-user-question/index.ts` for an extension called `index`, and the screen lagged a keystroke behind a reload. Both fixed.
|
||||
|
||||
## Junk TUIOS sessions — research and plan
|
||||
|
||||
`tuios ls --all-hosts` shows **37 sessions. 21 are from the closed project's tests**: `harness-demo-card-*` (18) and `office-test-1*` (3). The rest are yours and should stay — `office` (32 panes, attached), `paperclip-harness` (the layout), `factory`, and your personal ones.
|
||||
|
||||
**Nothing was killed.** That is destructive and the list is the evidence to decide on. Proposed, in `docs/SESSIONS.md`:
|
||||
|
||||
1. Kill the 21 by explicit pattern, with a `--dry-run` that only prints.
|
||||
2. A `bin/prune` that shows sessions by age and pane count, and refuses any attached session.
|
||||
3. A rule that every test script kills the session it creates — those 21 exist because creating was one command and cleaning up was not.
|
||||
4. Never prune `paperclip-harness`: its panes are the layout, rebuilt by `R`.
|
||||
|
||||
## Where to find a Pi session
|
||||
|
||||
```
|
||||
~/.pi/paperclips/<timestamp>-<agentId>.jsonl 178 files here
|
||||
GET /api/agents/{id}/task-sessions → task → session file + folder
|
||||
```
|
||||
|
||||
Open it with `pi --resume` (pick from Pi's list), or `pi --session <file>` for that exact conversation — the same flag Paperclip uses. Your instinct was right: the folder plus `--resume` is enough; a transcript tab is optional later.
|
||||
|
||||
## The test plan, as written earlier
|
||||
|
||||
1. Create a task in `New task>new` with a blocker and a verify command; see it in `Board>board`.
|
||||
2. Assign it in `Board>board`, then watch it in `Agents>agents` — roster, runs, its log.
|
||||
3. Let it finish; read the diff in `Work>work` and the verdict in `Work>review`.
|
||||
4. Merge with `bin/merge`; confirm the verify command passes on `main`.
|
||||
5. Open the dependent task and confirm it can now proceed.
|
||||
6. Press `R` in `Repair>repair` and confirm all eight workspaces return.
|
||||
7. Change an agent's model in `Agents>agents` settings and confirm it applies to the *next* run only.
|
||||
|
||||
All eight workspaces are running on the new build. Committed as `1f8731f`.
|
||||
|
||||
## Source paths observed
|
||||
|
||||
- `home/sam/.local/share/paperclip-harness/wrappers/403de1f7-645c-4d35-bc7e-19b01d77bacc.sh`
|
||||
- `paperclip-harness/tui/paperclip`
|
||||
- `home/sam/paseo/projects/paperclip-harness/docs/SESSIONS.md`
|
||||
- `paperclipai/paperclip/paperclip`
|
||||
- `local/556e0be78e/archify`
|
||||
- `.local/share/paperclip-harness/wrappers`
|
||||
- `home/sam/.agents/extensions/ask-user-question/index.ts`
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 82%
|
||||
- Reason: Captured factual repo structure/configuration patterns from rich discovery
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 22:15:52 -->
|
||||
|
||||
- session: [[packs/paperclip-harness/80-sessions/paperclip-harness-skills-extension-pickers-built-junk-tuios-|Paperclip harness: skills/extension pickers built, junk TUIOS session research, Pi session lookup]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-paperclipai-2026-11-10-22-15-52|Rich discovery: paperclipai 2026-11-10 22:15:52]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclipai|paperclipai]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|paperclipai repository structure and configuration patterns]]
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
type: session
|
||||
id: session.paperclip-harness.paperclip-harness-skills-extension-pickers-built-junk-tuios-
|
||||
title: Paperclip harness: skills/extension pickers built, junk TUIOS session research, Pi session lookup
|
||||
status: active
|
||||
source_of_truth: false
|
||||
freshness: current
|
||||
last_reviewed: 2026-11-10
|
||||
tags:
|
||||
- pack/paperclip-harness
|
||||
- agent-memory/session
|
||||
- paperclip-harness
|
||||
- skills-picker
|
||||
- extensions-picker
|
||||
- tuios
|
||||
- sessions
|
||||
- pi
|
||||
- test-plan
|
||||
- docs/SESSIONS.md
|
||||
---
|
||||
|
||||
# Paperclip harness: skills/extension pickers built, junk TUIOS session research, Pi session lookup
|
||||
|
||||
Rich discovery snapshot for paperclip-harness (repo at ~/paseo/projects/paperclip-harness, active pack 'paperclip-harness'). Committed as 1f8731f "Skill and extension picker for Paperclip agents; session notes and cleanup plan".
|
||||
|
||||
## Skills picker (Agents>agents, 5th tab)
|
||||
Reads same source as pi-config (~/.agents/skills) plus Paperclip company list and the chosen agent's own list; marks each row (e.g. 'in Paperclip' / 'not in Paperclip').
|
||||
Space on a skill Paperclip doesn't know: copies it into the company managed folder, imports it, assigns to THIS agent only (e.g. 'local/556e0be78e/archify'). Toggling off removes it, restoring original desiredSkills (verified on agent 'Builder').
|
||||
|
||||
## Extensions picker (Agents>agents, 6th tab)
|
||||
Paperclip has no extension model, so equivalent = per-agent command. Lists ~/.agents/extensions. Turning one on writes wrapper ~/.local/share/paperclip-harness/wrappers/<agentId>.sh containing '#!/bin/sh' + 'exec pi --extension <ext path>/index.ts "$@"' and sets adapterConfig.command to that file (keeps model/folder untouched). Turning last one off deletes wrapper and restores command to plain 'pi'. Unit test pins write->read-back->remove. Two bugs fixed during testing: wrapper reader mistook '.../ask-user-question/index.ts' for extension named 'index'; screen lagged a keystroke behind reload.
|
||||
|
||||
## TUIOS sessions research (no destructive action taken)
|
||||
'tuios ls --all-hosts' shows 37 sessions; 21 are from the closed project's tests ('harness-demo-card-*' x18, 'office-test-1*' x3). Keep: 'office' (32 panes, attached), 'paperclip-harness' (the layout), 'factory', personal ones. Plan written to docs/SESSIONS.md: (1) kill 21 by explicit pattern with --dry-run first; (2) bin/prune shows sessions by age+pane count, refuses attached sessions; (3) rule that every test script kills the session it creates; (4) never prune paperclip-harness (panes are the layout, rebuilt by R).
|
||||
|
||||
## Pi session lookup
|
||||
Transcripts: ~/.pi/paperclips/<timestamp>-<agentId>.jsonl (178 files). 'GET /api/agents/{id}/task-sessions' maps task -> session file + folder. Open with 'pi --resume' (pick from list) or 'pi --session <file>' (same flag Paperclip uses).
|
||||
|
||||
## Manual test plan (7 steps) for end-to-end flow
|
||||
1. Create task in New task>new with blocker + verify command; see in Board>board. 2. Assign in Board, watch in Agents (roster, runs, log). 3. Let finish; read diff in Work>work, verdict in Work>review. 4. Merge with bin/merge; confirm verify passes on main. 5. Open dependent task, confirm it proceeds. 6. Press R in Repair>repair, confirm all 8 workspaces return. 7. Change agent model in Agents settings, confirm applies to NEXT run only. All 8 workspaces running new build.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 90%
|
||||
- Reason: Final answer contains many durable, evidence-backed discoveries (component behavior, file paths, counts, cleanup plan, test plan) worth one rich sanitized snapshot.
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 22:15:52 -->
|
||||
|
||||
- session: [[packs/paperclip-harness/80-sessions/paperclip-harness-skills-extension-pickers-built-junk-tuios-|Paperclip harness: skills/extension pickers built, junk TUIOS session research, Pi session lookup]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-paperclipai-2026-11-10-22-15-52|Rich discovery: paperclipai 2026-11-10 22:15:52]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclipai|paperclipai]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|paperclipai repository structure and configuration patterns]]
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
type: session
|
||||
id: session.paperclip-harness.rich-discovery-paperclipai-2026-11-10-22-15-52
|
||||
title: Rich discovery: paperclipai 2026-11-10 22:15:52
|
||||
status: active
|
||||
source_of_truth: false
|
||||
freshness: current
|
||||
last_reviewed: 2026-11-10
|
||||
tags:
|
||||
- pack/paperclip-harness
|
||||
- agent-memory/session
|
||||
- autolearn
|
||||
- rich-discovery
|
||||
- repo/paperclipai
|
||||
---
|
||||
|
||||
# Rich discovery: paperclipai 2026-11-10 22:15:52
|
||||
|
||||
Sanitized rich discovery snapshot captured automatically from the completed turn.
|
||||
|
||||
|
||||
## Source paths observed
|
||||
|
||||
- `home/sam/.local/share/paperclip-harness/wrappers/403de1f7-645c-4d35-bc7e-19b01d77bacc.sh`
|
||||
- `paperclip-harness/tui/paperclip`
|
||||
- `home/sam/paseo/projects/paperclip-harness/docs/SESSIONS.md`
|
||||
- `paperclipai/paperclip/paperclip`
|
||||
- `local/556e0be78e/archify`
|
||||
- `.local/share/paperclip-harness/wrappers`
|
||||
- `home/sam/.agents/extensions/ask-user-question/index.ts`
|
||||
|
||||
## Final answer snapshot
|
||||
|
||||
The picker is built and driven end to end.
|
||||
|
||||
## Skills picker — `Agents>agents`, fifth tab
|
||||
|
||||
It reads the same source `pi-config` reads (`~/.agents/skills`), plus Paperclip's company list and the chosen agent's own list, and marks every row:
|
||||
|
||||
```
|
||||
Builder · space toggles the chosen skill
|
||||
▸ archify not in Paperclip
|
||||
caveman not in Paperclip
|
||||
nixos-workflow in Paperclip
|
||||
obsidian-cli in Paperclip
|
||||
project-docs in Paperclip
|
||||
```
|
||||
|
||||
Pressing space on a skill that Paperclip does not know copies it into the company managed folder, imports it, and assigns it **to this agent only**. Verified on `Builder`:
|
||||
|
||||
```
|
||||
before desiredSkills: ['paperclipai/paperclip/paperclip']
|
||||
space → 'local/556e0be78e/archify' added by Paperclip
|
||||
space → removed again; back to the original list
|
||||
```
|
||||
|
||||
That is the picker you asked for, and every step is a real call, not a plan.
|
||||
|
||||
## Extensions picker — sixth tab
|
||||
|
||||
Paperclip has no extension model, so the equivalent is the per-agent command. This tab lists `~/.agents/extensions`, and turning one on writes:
|
||||
|
||||
```
|
||||
~/.local/share/paperclip-harness/wrappers/<agentId>.sh
|
||||
#!/bin/sh
|
||||
exec pi --extension /home/sam/.agents/extensions/ask-user-question/index.ts "$@"
|
||||
```
|
||||
|
||||
and sets `adapterConfig.command` to that file — keeping the agent's model and folder untouched. Turning the last one off deletes the wrapper and puts the command back to plain `pi` (verified: `command: pi`, no wrapper file). A unit test pins write → read-back → remove, because a wrong wrapper would stop an agent from starting at all.
|
||||
|
||||
Two bugs found while testing: the wrapper reader mistook `…/ask-user-question/index.ts` for an extension called `index`, and the screen lagged a keystroke behind a reload. Both fixed.
|
||||
|
||||
## Junk TUIOS sessions — research and plan
|
||||
|
||||
`tuios ls --all-hosts` shows **37 sessions. 21 are from the closed project's tests**: `harness-demo-card-*` (18) and `office-test-1*` (3). The rest are yours and should stay — `office` (32 panes, attached), `paperclip-harness` (the layout), `factory`, and your personal ones.
|
||||
|
||||
**Nothing was killed.** That is destructive and the list is the evidence to decide on. Proposed, in `docs/SESSIONS.md`:
|
||||
|
||||
1. Kill the 21 by explicit pattern, with a `--dry-run` that only prints.
|
||||
2. A `bin/prune` that shows sessions by age and pane count, and refuses any attached session.
|
||||
3. A rule that every test script kills the session it creates — those 21 exist because creating was one command and cleaning up was not.
|
||||
4. Never prune `paperclip-harness`: its panes are the layout, rebuilt by `R`.
|
||||
|
||||
## Where to find a Pi session
|
||||
|
||||
```
|
||||
~/.pi/paperclips/<timestamp>-<agentId>.jsonl 178 files here
|
||||
GET /api/agents/{id}/task-sessions → task → session file + folder
|
||||
```
|
||||
|
||||
Open it with `pi --resume` (pick from Pi's list), or `pi --session <file>` for that exact conversation — the same flag Paperclip uses. Your instinct was right: the folder plus `--resume` is enough; a transcript tab is optional later.
|
||||
|
||||
## The test plan, as written earlier
|
||||
|
||||
1. Create a task in `New task>new` with a blocker and a verify command; see it in `Board>board`.
|
||||
2. Assign it in `Board>board`, then watch it in `Agents>agents` — roster, runs, its log.
|
||||
3. Let it finish; read the diff in `Work>work` and the verdict in `Work>review`.
|
||||
4. Merge with `bin/merge`; confirm the verify command passes on `main`.
|
||||
5. Open the dependent task and confirm it can now proceed.
|
||||
6. Press `R` in `Repair>repair` and confirm all eight workspaces return.
|
||||
7. Change an agent's model in `Agents>agents` settings and confirm it applies to the *next* run only.
|
||||
|
||||
All eight workspaces are running on the new build. Committed as `1f8731f`.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 86%
|
||||
- Reason: Preserve full sanitized discovery detail from a rich investigation turn
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 22:15:52 -->
|
||||
|
||||
- session: [[packs/paperclip-harness/80-sessions/paperclip-harness-skills-extension-pickers-built-junk-tuios-|Paperclip harness: skills/extension pickers built, junk TUIOS session research, Pi session lookup]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-paperclipai-2026-11-10-22-15-52|Rich discovery: paperclipai 2026-11-10 22:15:52]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclipai|paperclipai]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|paperclipai repository structure and configuration patterns]]
|
||||
BIN
bin/harness
BIN
bin/harness
Binary file not shown.
@@ -22,6 +22,7 @@ it is a pointer and should be deleted or replaced.
|
||||
| `docs/UI-LAYOUT.md` | this project | what each page must show, where each fact comes from, and the three candidate layouts |
|
||||
| `docs/PLAN-INTERFACE.md` | this project | the plan: Paperclip object → screen, what exists, what is missing, and in what order |
|
||||
| `docs/SESSIONS.md` | this project | the two kinds of session, where Pi's conversations are, and the plan for the junk TUIOS sessions |
|
||||
| `docs/TEST-PLAN.md` | this project | the test plan: every step, every key, every expected result |
|
||||
|
||||
## What is not a document of this project
|
||||
|
||||
|
||||
155
docs/TEST-PLAN.md
Normal file
155
docs/TEST-PLAN.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# The test plan, with every key and every expected result
|
||||
|
||||
Sit at the keyboard and follow this in order. Each step says what to press, what you should
|
||||
see, and when to stop. Nothing here needs a shell inside the factory; where a shell is needed
|
||||
it is `Shell>shell`.
|
||||
|
||||
**Before you start:** the eight workspaces are already built. `R` in `Repair>repair` rebuilds
|
||||
them at any time. If a pane looks wrong, press `R` and wait ten seconds.
|
||||
|
||||
## The words, once, plainly
|
||||
|
||||
| Word | Means |
|
||||
|---|---|
|
||||
| task | one unit of work in Paperclip, with its own thread, its own copy of the code, its own cost |
|
||||
| blocker | another task that must reach `done` before this one may start. A link between two tasks, stored by Paperclip. |
|
||||
| verify command | a shell command that exits 0 only when the task is really finished. It runs in the task's copy of the code. |
|
||||
| assign | give the task to one agent. This is what wakes the agent and makes it start. |
|
||||
| worktree | the task's own copy of the repository, made by Paperclip, so two tasks cannot overwrite each other |
|
||||
| run | one execution of one agent. A task usually has one or two. |
|
||||
|
||||
The eight workspaces are **not** agents. Workspaces are TUIOS pages. The agents are six
|
||||
records inside Paperclip: `researcher`, `System`, `Hub`, `Chief of Staff`, `Documenter`,
|
||||
`Builder`. You see them all in `Agents>agents`.
|
||||
|
||||
## Step 0 — check the ground
|
||||
|
||||
1. Go to `Repair>repair`. The health tab should say **everything checked passes**.
|
||||
2. Go to `Agents>agents`. The roster should list six agents, all `idle` except any that are
|
||||
paused. If `Builder` says `paused`, select it with `↑`/`↓` and press `P` to resume.
|
||||
|
||||
If either is wrong, stop and say what the screen shows.
|
||||
|
||||
## Step 1 — create a task
|
||||
|
||||
Go to `New task>new`. The form has five fields. Type into the first, press `Enter`, and the
|
||||
next field takes the cursor. `Tab` also moves forward, `Shift-Tab` back.
|
||||
|
||||
Fill it in exactly like this:
|
||||
|
||||
| Field | Type |
|
||||
|---|---|
|
||||
| Title | `Add a file named STATUS.md with one line` |
|
||||
| What it must do | `Create STATUS.md at the repository root containing exactly one line: the factory is running. Change no other file. Commit it.` |
|
||||
| Must finish first | leave empty (just `Enter`) |
|
||||
| Proves it is done | `test -s STATUS.md` |
|
||||
| Assign to | `yes` |
|
||||
|
||||
`Enter` on the last field creates it. The pane closes and prints `created AUD-1xx, handed to
|
||||
an agent`.
|
||||
|
||||
**Expected:** within about two seconds the pane exits and the task exists. Go to `Board>board`
|
||||
and look at the top: your task is under `IN PROGRESS`, assigned to `Builder`.
|
||||
|
||||
**Stop if:** an error line appears. The text is Paperclip's own message; copy it.
|
||||
|
||||
## Step 2 — watch it work
|
||||
|
||||
Stay in `Board>board`. The row for your task should move from `todo` to `in progress` and then
|
||||
to `done` within a minute or two.
|
||||
|
||||
Then go to `Agents>agents`:
|
||||
|
||||
1. The roster tab: `Builder` should show a run in progress, or `idle` with the money increased.
|
||||
2. Press `]` once to the **runs** tab. The newest run is on top, with agent, state, what woke
|
||||
it (`assignment`), duration and the task identifier.
|
||||
3. Select the top run with `↑` and press `Enter`. The **log** tab opens with what Pi actually
|
||||
did: the prompt, its reasoning, its tool calls.
|
||||
4. Press `[` twice to come back.
|
||||
|
||||
**Expected:** one run, `succeeded`, woken by `assignment`.
|
||||
|
||||
## Step 3 — read what changed
|
||||
|
||||
Go to `Work>work`. It follows the task you chose on the board.
|
||||
|
||||
1. `runs` tab: the run timeline, then the activity.
|
||||
2. `]` to **change**: the worktree path, the branch, the commit, `STATUS.md`, and the diff
|
||||
(green `+` lines).
|
||||
3. `]` to **facts**: the folder, branch, base and cost.
|
||||
4. `]` to **review**: either a recorded verdict or "no review recorded".
|
||||
|
||||
**Expected:** the diff shows exactly one file, `STATUS.md`, one line added.
|
||||
|
||||
## Step 4 — merge it
|
||||
|
||||
This is the one step that needs a shell, because a merge takes a lock and re-runs the checks.
|
||||
|
||||
1. Go to `Shell>shell`. You are in the project folder.
|
||||
2. Type: `bin/merge AUD-1xx --check` (your identifier), press `Enter`.
|
||||
|
||||
**Expected:** it rebases, runs `test -s STATUS.md`, runs the review, and prints `checked only;
|
||||
nothing merged`.
|
||||
|
||||
3. Type: `bin/merge AUD-1xx`, press `Enter`.
|
||||
|
||||
**Expected:** the same checks, then `merged into main at <commit>`.
|
||||
|
||||
4. Type `git log --oneline -3`, press `Enter`. Your task's merge commit is at the top.
|
||||
|
||||
**Stop if:** it says `refused`. The reason is printed and also written on the task, where
|
||||
`Work>review` shows it.
|
||||
|
||||
## Step 5 — a task that must wait for another
|
||||
|
||||
1. `New task>new` again. Title `Read STATUS.md and quote it`.
|
||||
2. What it must do: `Read STATUS.md at the repository root and quote its contents in a comment on this task. Change no file.`
|
||||
3. **Must finish first**: the identifier of the task you just merged, for example `AUD-171`.
|
||||
4. Proves it is done: leave empty.
|
||||
5. Assign to: `yes`.
|
||||
|
||||
**Expected:** `Board>board` shows it under `TODO` with `waits on AUD-171` beside it, and it does
|
||||
**not** start. That is the blocker: Paperclip holds it until the other task is `done` — which it
|
||||
is, so the agent may start. If the blocker were unfinished, it would sit there.
|
||||
|
||||
To see the waiting case, do the same but block the new task on a task that is still `todo`.
|
||||
|
||||
## Step 6 — change an agent
|
||||
|
||||
Go to `Agents>agents`, then `]` four times to **settings**.
|
||||
|
||||
1. `↑`/`↓` to `model`, press `Enter`, edit the text, press `Enter` to save.
|
||||
2. `↑`/`↓` to `monthly budget`, press `Enter`, type a number of cents, press `Enter`.
|
||||
3. `p` pauses the chosen agent, `P` resumes it, `w` wakes it now.
|
||||
|
||||
**Expected:** the row shows the new value immediately and Paperclip has it. A model change
|
||||
applies to that agent's **next** run, never one already running.
|
||||
|
||||
**Note:** you can set an agent at any time — before a run, between runs, while paused. What you
|
||||
cannot do is change the model *of a run that has already started*; that is why the next run
|
||||
picks it up.
|
||||
|
||||
## Step 7 — skills and extensions per agent
|
||||
|
||||
Still in `Agents>agents`, `]` to **skills**.
|
||||
|
||||
1. `↑`/`↓` to a skill marked `not in Paperclip`, press `space`.
|
||||
|
||||
**Expected:** the line changes to `on this agent`. That skill — and no other — is now in that
|
||||
agent's list. `space` again removes it.
|
||||
|
||||
`]` once more to **extensions**. `space` on one writes a wrapper for that agent only and sets
|
||||
its command; `space` again removes it.
|
||||
|
||||
## Step 8 — rebuild
|
||||
|
||||
Go to `Repair>repair` and press `R`.
|
||||
|
||||
**Expected:** every pane closes and comes back within about ten seconds, in the same order:
|
||||
Shell, Board, Work, Agents, Reply, New task, Project, Repair. The third tab shows the rebuild
|
||||
log.
|
||||
|
||||
## What to write down
|
||||
|
||||
For each step: what you pressed, what appeared, and anything that did not match. That is more
|
||||
useful than a verdict, because it says where the interface and Paperclip disagree.
|
||||
@@ -51,7 +51,7 @@ what it shows is never a second copy of anything.
|
||||
| Pane | Shows | Status |
|
||||
|---|---|---|
|
||||
| `New task>form` | title, what it must do, what must finish first, the command that proves it is done, whether to assign | built |
|
||||
| `New task>guidance` | what a task needs: one thing, a command, a boundary, a blocker | built |
|
||||
| `New task>guidance` | what each of the five fields means, with an example for each, and a short glossary | built |
|
||||
| `New task>preview` | exactly the description the agent will receive | built |
|
||||
|
||||
## 6. Agents — the missing workspace
|
||||
|
||||
@@ -224,19 +224,42 @@ func (m newTaskModel) previewLines(width int) []string {
|
||||
return out
|
||||
}
|
||||
|
||||
// guidanceLines answers the four questions the form asks, with examples rather
|
||||
// than metaphors. If a line here needs a second reading, it is the wrong line.
|
||||
func (m newTaskModel) guidanceLines(width int) []string {
|
||||
out := []string{"", groupHeading("what a task needs", 4, width-2), ""}
|
||||
add := func(k, v string) {
|
||||
out = append(out, " "+lipgloss.NewStyle().Foreground(lipgloss.Color(active.Accent)).Render(k))
|
||||
for _, ln := range wrap(v, max(8, width-4)) {
|
||||
out := []string{"", groupHeading("the five fields", -1, width-2), ""}
|
||||
add := func(field, what, example string) {
|
||||
out = append(out, " "+lipgloss.NewStyle().Foreground(lipgloss.Color(active.Accent)).Bold(true).Render(field))
|
||||
for _, ln := range wrap(what, max(8, width-4)) {
|
||||
out = append(out, " "+mutedStyle2().Render(ln))
|
||||
}
|
||||
out = append(out, " "+dimStyle().Render("example: "+example))
|
||||
out = append(out, "")
|
||||
}
|
||||
add("Title", "One sentence naming the change. It becomes the task title in Paperclip.",
|
||||
"Add a CHANGELOG.md with an Unreleased section")
|
||||
add("What it must do", "The files to create or change, by path, and the exact behaviour. Mention what must NOT be touched.",
|
||||
"Create CHANGELOG.md at the repository root. One section titled Unreleased with three bullets. Change no other file. Commit it.")
|
||||
add("Must finish first", "The identifier of another task, for example AUD-171. Paperclip then records a real blocker edge and will not let this task run before that one is done. Leave it empty when nothing must come first.",
|
||||
"AUD-171")
|
||||
add("Proves it is done", "A shell command that exits 0 only when the work is right. It runs in the task's own copy of the code. Leave it empty and the task will be accepted on the agent's word, which is a weaker test.",
|
||||
"test -s CHANGELOG.md or make test")
|
||||
add("Assign to", "yes, or empty. yes hands the task to the configured agent as soon as it is created; empty leaves it for a person to assign on the board.",
|
||||
"yes")
|
||||
|
||||
out = append(out, groupHeading("what these words mean", -1, width-2), "")
|
||||
for _, pair := range [][2]string{
|
||||
{"blocker", "Another task that must reach done before this one may start. It is a link between two tasks in Paperclip, not a sentence."},
|
||||
{"verify command", "The command that decides the task is finished. Run in the task's worktree; exit 0 means finished."},
|
||||
{"assign", "Giving the task to one agent. That is what wakes the agent and makes it start work."},
|
||||
{"worktree", "The task's own copy of the repository, made by Paperclip. Two tasks cannot overwrite each other because of it."},
|
||||
} {
|
||||
out = append(out, " "+lipgloss.NewStyle().Foreground(lipgloss.Color(active.Text)).Render(pair[0]))
|
||||
for _, ln := range wrap(pair[1], max(8, width-4)) {
|
||||
out = append(out, " "+mutedStyle2().Render(ln))
|
||||
}
|
||||
out = append(out, "")
|
||||
}
|
||||
add("one thing", "A task that asks for two things cannot be judged, only argued about.")
|
||||
add("a command", "The verify command decides when the work is finished. The agent does not.")
|
||||
add("a boundary", "Say which files may change. An unbounded task is how a review becomes an autopsy.")
|
||||
add("a blocker", "If it must wait, name the task it waits for. A sentence in the description is not a blocker.")
|
||||
return out
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user