From 9933672c2efd1c14582faac090f536f283e3f301 Mon Sep 17 00:00:00 2001 From: Wenxin Duan Date: Mon, 7 Sep 2026 10:23:10 +0800 Subject: [PATCH] docs: align implementation plan with behavior tests --- .../plans/2026-09-07-agent-studio-mini.md | 47 +++++-------------- 1 file changed, 12 insertions(+), 35 deletions(-) diff --git a/docs/superpowers/plans/2026-09-07-agent-studio-mini.md b/docs/superpowers/plans/2026-09-07-agent-studio-mini.md index 9e1b06e..447730a 100644 --- a/docs/superpowers/plans/2026-09-07-agent-studio-mini.md +++ b/docs/superpowers/plans/2026-09-07-agent-studio-mini.md @@ -37,7 +37,6 @@ - Create: `packages/shared/package.json` - Create: `packages/shared/tsconfig.json` - Create: `packages/shared/src/index.ts` -- Create: `packages/shared/tests/smoke.test.ts` - Create: `packages/harness/package.json` - Create: `packages/harness/tsconfig.json` - Create: `apps/server/package.json` @@ -51,22 +50,11 @@ - Consumes: Node.js 20+ and pnpm 11 available in the development environment. - Produces: root commands `dev`, `lint`, `typecheck`, `test`, and `build`; workspace package names `@agent-studio/shared` and `@agent-studio/harness`. -- [ ] **Step 1: Add the workspace smoke test** - -```ts -// packages/shared/tests/smoke.test.ts -import { describe, expect, it } from "vitest"; - -describe("workspace", () => { - it("runs TypeScript tests", () => expect(true).toBe(true)); -}); -``` - -- [ ] **Step 2: Create strict workspace configuration and package scripts** +- [ ] **Step 1: Create strict workspace configuration and package scripts** Root scripts must delegate with `pnpm -r`, keep `dev` parallel, and make `test` use Vitest in run mode. `tsconfig.base.json` must enable `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `useUnknownInCatchVariables`, `verbatimModuleSyntax`, and `noEmit` for checking. `.env.example` must contain only the empty/default values from the design spec. -- [ ] **Step 3: Install current stable dependencies** +- [ ] **Step 2: Install current stable dependencies** Run: @@ -79,7 +67,7 @@ pnpm --filter @agent-studio/web add @agent-studio/shared react react-dom @assist pnpm --filter @agent-studio/web add -D vite @vitejs/plugin-react jsdom @testing-library/react @testing-library/user-event @testing-library/jest-dom ``` -- [ ] **Step 4: Record and inspect the installed public API** +- [ ] **Step 3: Record and inspect the installed public API** Run: @@ -91,13 +79,13 @@ rg "useExternalStoreRuntime|AttachmentAdapter|ThreadPrimitive|ComposerPrimitive" Write exact dependency versions and any material signature differences into a temporary commit note in `README.md`; Task 16 expands it into the final version/API section. -- [ ] **Step 5: Verify the baseline** +- [ ] **Step 4: Verify the baseline** Run: `pnpm test && pnpm typecheck && pnpm lint` -Expected: the smoke test passes and all packages typecheck/lint without ignored errors. +Expected: all packages typecheck/lint without ignored errors; packages that do not yet contain tests exit cleanly through their explicit `--passWithNoTests` baseline configuration. -- [ ] **Step 6: Commit** +- [ ] **Step 5: Commit** ```bash git add package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json eslint.config.js .gitignore .env.example packages apps README.md @@ -1035,36 +1023,25 @@ git commit -m "test: cover complete Agent Studio flow" - Create: `docs/security-boundaries.md` - Create: `docs/classroom-demo.md` - Create: `docs/production-roadmap.md` -- Create: `packages/harness/tests/documentation.test.ts` **Interfaces:** - Consumes: actual dependency versions, commands, routes and observed behavior from Tasks 1–16. - Produces: complete operator/trainer documentation with Mermaid diagrams and no unverified claims. -- [ ] **Step 1: Write documentation assertions** - -Create a focused Vitest that reads the Markdown files and asserts README contains the exact phrases `Pi does not provide an OS sandbox`, `Project Trust is not a sandbox`, `skill.requested`, `skill.loaded`, all root commands, and every required documentation link. - -- [ ] **Step 2: Verify red state** - -Run: `pnpm --filter @agent-studio/harness test -- documentation` - -Expected: FAIL because final documentation is incomplete. - -- [ ] **Step 3: Write README and five guides** +- [ ] **Step 1: Write README and five guides** Document purpose, actual versions/API differences, architecture and Agent Loop diagrams, boundaries, directory tree, setup, environment and Settings model configuration, credential lifetime, image chain, exact demo prompt, Approve/Deny behavior, progressive disclosure, inferred Skill events, in-memory/single-process limits, test commands and production roadmap. Security guide explicitly explains Node process inheritance and the need for Docker/VM/micro-VM/remote sandbox for untrusted work. -- [ ] **Step 4: Verify documentation** +- [ ] **Step 2: Verify documentation against actual behavior** -Run: `pnpm --filter @agent-studio/harness test -- documentation` +Run every documented setup, test and build command. Compare documented versions with `pnpm list -r --depth 0`, routes with the Fastify route registry, and environment names with `apps/server/src/config.ts`. Render Mermaid blocks in a compatible preview and inspect every internal file link. -Expected: PASS and no stale commands, versions or route names. +Expected: all commands succeed and no documented version, route, environment name, link or security claim disagrees with the implementation. -- [ ] **Step 5: Commit** +- [ ] **Step 3: Commit** ```bash -git add README.md docs packages/harness/tests +git add README.md docs git commit -m "docs: add Agent Studio teaching guide" ```