Loaded Markdown

Research Notes

docs/research-notes.md

Markdown viewer modes

Research Notes

Skill Writing

Findings:

  • The trigger description is the most important skill line.
  • Keep SKILL.md short; move detail to one-level reference files.
  • Use numbered workflows for multi-step tasks.
  • Match instruction precision to fragility.
  • Build validation loops into the workflow.
  • Avoid explaining what agents already know.

Sources:

Zod First

Decision:

  • Zod in packages/core/src/schemas.ts is the source of truth.
  • JSON Schema is generated for external tools and review.
  • Semantic cross-link validation stays in TypeScript because it is easier to maintain than encoding it in JSON Schema.

Sources:

Viewer Payloads

Decision:

  • Hash payloads are the PlanPack viewer handoff target.
  • Default to Brotli-compressed viewer JSON.
  • Measure full JSON, viewer JSON, and TOON before changing transport.
  • Hosted JSON is a fallback for large plans, private plans, or evidence-heavy plans.

Observed for examples/2026-06-03-comment-draft-autosave.planpack.json:

  • Full minified JSON: 10907 chars.
  • Viewer minified JSON: 5117 chars.
  • Brotli viewer JSON hash: 1743 chars.
  • TOON viewer payload: 5403 chars.
  • Brotli TOON hash: 1774 chars.

Sources:

Skills CLI

Finding:

  • npx skills installs skill packages and syncs agent skill directories.
  • PlanPack profile prompts are not the same thing as Skills, so this repo keeps profiles under agent-profiles/.
  • The PlanPack SKILL.md can later be installed through the skills CLI after the format stabilizes.

Source:

  • npx skills --help

Plan Revisions

Decision:

  • Keep durable revision summaries in revisions.
  • Include revision type, reason, changedPaths, and optional status transition.
  • Use JSONL only for detailed audit events. Do not require it for viewer state.

Claude Workflows

Findings:

  • Dynamic workflows move orchestration into a repeatable script; intermediate state lives outside the main context.
  • Use workflows for high-agent-count audits, migrations, cross-checked research, or hard plans drafted from multiple angles.
  • Human sign-off should be modeled as a separate stage or run because workflows do not take arbitrary mid-run user input.
  • Claude's taxonomy is useful: subagents are workers, skills are reusable procedures, agent teams use shared tasks, workflows hold the plan in code.
  • Subagent profiles should declare capability envelopes: tools, model/effort, isolation, max turns, preloaded skills, and memory scope.
  • Hooks and goals reinforce the PlanPack validation contract: done means transcript-visible evidence, not just agent confidence.

PlanPack decisions:

  • Keep PlanPack JSON as the compact orchestration artifact, not a transcript.
  • Let reusable skills/profiles hold execution details; plan steps reference those by ID.
  • Treat the orchestrator as the owner of nested delegation. Workers return structured handoffs and should not recursively manage teams.
  • Add workflow-style fields only when real runs need them; existing pipeline.mode, dependsOn, parallelization, and handoff contracts cover v0.

Sources:

Mermaid Pipeline Views

Findings:

  • Mermaid should be generated from PlanPack JSON, not authored as the source of truth.
  • The strongest skill pattern is route by diagram intent, load only the needed guide, generate, validate, then render/export.
  • Mermaid can act as an intermediate representation for validators or renderers, not just a pretty artifact.
  • Keep renderer/export details separate from plan authoring; SVG/PNG/GIF themes are late-stage choices.

PlanPack decisions:

  • Add a future diagram command or skill around planpack diagram --type pipeline|handoff|validation|timeline.
  • Generate .mmd deterministically from pipeline, dependsOn, parallelization, milestones, and validationContract.
  • Validate Mermaid before embedding it in the viewer or docs.
  • Prefer a compact PlanPack-specific diagram skill over installing broad, verbose Mermaid skills as always-on context.

Sources:

Markdown Source113 lines
1# Research Notes2 3## Skill Writing4 5Findings:6- The trigger `description` is the most important skill line.7- Keep `SKILL.md` short; move detail to one-level reference files.8- Use numbered workflows for multi-step tasks.9- Match instruction precision to fragility.10- Build validation loops into the workflow.11- Avoid explaining what agents already know.12 13Sources:14- https://www.skills.sh/docs15- https://www.mdskills.ai/docs/skill-best-practices16- Local skill creator: `~/.codex/skills/.system/skill-creator/SKILL.md`17 18## Zod First19 20Decision:21- Zod in `packages/core/src/schemas.ts` is the source of truth.22- JSON Schema is generated for external tools and review.23- Semantic cross-link validation stays in TypeScript because it is easier to maintain than encoding it in JSON Schema.24 25Sources:26- https://zod.dev/json-schema27- https://platform.openai.com/docs/guides/structured-outputs28 29## Viewer Payloads30 31Decision:32- Hash payloads are the PlanPack viewer handoff target.33- Default to Brotli-compressed viewer JSON.34- Measure full JSON, viewer JSON, and TOON before changing transport.35- Hosted JSON is a fallback for large plans, private plans, or evidence-heavy plans.36 37Observed for `examples/2026-06-03-comment-draft-autosave.planpack.json`:38- Full minified JSON: 10907 chars.39- Viewer minified JSON: 5117 chars.40- Brotli viewer JSON hash: 1743 chars.41- TOON viewer payload: 5403 chars.42- Brotli TOON hash: 1774 chars.43 44Sources:45- https://github.com/toon-format/toon46- https://chromium.googlesource.com/chromium/src/+/main/docs/security/url_display_guidelines/url_display_guidelines.md47- https://developer.mozilla.org/en-US/docs/Web/API/URL/hash48 49## Skills CLI50 51Finding:52- `npx skills` installs skill packages and syncs agent skill directories.53- PlanPack profile prompts are not the same thing as Skills, so this repo keeps profiles under `agent-profiles/`.54- The PlanPack `SKILL.md` can later be installed through the skills CLI after the format stabilizes.55 56Source:57- `npx skills --help`58 59## Plan Revisions60 61Decision:62- Keep durable revision summaries in `revisions`.63- Include revision `type`, `reason`, `changedPaths`, and optional status transition.64- Use JSONL only for detailed audit events. Do not require it for viewer state.65 66## Claude Workflows67 68Findings:69- Dynamic workflows move orchestration into a repeatable script; intermediate state lives outside the main context.70- Use workflows for high-agent-count audits, migrations, cross-checked research, or hard plans drafted from multiple angles.71- Human sign-off should be modeled as a separate stage or run because workflows do not take arbitrary mid-run user input.72- Claude's taxonomy is useful: subagents are workers, skills are reusable procedures, agent teams use shared tasks, workflows hold the plan in code.73- Subagent profiles should declare capability envelopes: tools, model/effort, isolation, max turns, preloaded skills, and memory scope.74- Hooks and goals reinforce the PlanPack validation contract: done means transcript-visible evidence, not just agent confidence.75 76PlanPack decisions:77- Keep PlanPack JSON as the compact orchestration artifact, not a transcript.78- Let reusable skills/profiles hold execution details; plan steps reference those by ID.79- Treat the orchestrator as the owner of nested delegation. Workers return structured handoffs and should not recursively manage teams.80- Add workflow-style fields only when real runs need them; existing `pipeline.mode`, `dependsOn`, `parallelization`, and handoff contracts cover v0.81 82Sources:83- https://code.claude.com/docs/en/workflows84- https://code.claude.com/docs/en/sub-agents85- https://code.claude.com/docs/en/skills86- https://code.claude.com/docs/en/agent-teams87- https://code.claude.com/docs/en/hooks88- https://code.claude.com/docs/en/goal89 90## Mermaid Pipeline Views91 92Findings:93- Mermaid should be generated from PlanPack JSON, not authored as the source of truth.94- The strongest skill pattern is route by diagram intent, load only the needed guide, generate, validate, then render/export.95- Mermaid can act as an intermediate representation for validators or renderers, not just a pretty artifact.96- Keep renderer/export details separate from plan authoring; SVG/PNG/GIF themes are late-stage choices.97 98PlanPack decisions:99- Add a future diagram command or skill around `planpack diagram --type pipeline|handoff|validation|timeline`.100- Generate `.mmd` deterministically from `pipeline`, `dependsOn`, `parallelization`, `milestones`, and `validationContract`.101- Validate Mermaid before embedding it in the viewer or docs.102- Prefer a compact PlanPack-specific diagram skill over installing broad, verbose Mermaid skills as always-on context.103 104Sources:105- https://www.skills.sh/softaworks/agent-toolkit/mermaid-diagrams106- https://www.skills.sh/imxv/pretty-mermaid-skills/pretty-mermaid107- https://www.skills.sh/spillwavesolutions/design-doc-mermaid/design-doc-mermaid108- https://www.skills.sh/trailofbits/skills/mermaid-to-proverif109- https://www.skills.sh/davila7/claude-code-templates/mermaid-diagram-specialist110- https://www.skills.sh/zc277584121/marketing-skills/mermaid-to-gif111- https://www.skills.sh/intellectronica/agent-skills/beautiful-mermaid112- https://www.skills.sh/axtonliu/axton-obsidian-visual-skills/mermaid-visualizer113