docs: add DESIGN.md, the portable bash + skills design

[keli-wen]

What

Add docs/DESIGN.md, which states how agy-staff is designed as a portable agent CLI tool: bash plus skills, with no hard dependency on a host, a worker CLI or a runtime library. Both READMEs get a new section, "Build one for another CLI" (「为其他 CLI 做一个」), with a copyable prompt for building the same kind of tool for another agent CLI. The top navigation links to it.

Closes #28.

Why

The design was spread across the README, REFERENCE.md, the skills, the templates and the release notes. Each is accurate for its reader, but none states the design as a whole or the reasons behind it. The same kind of delegation tool keeps being rebuilt for other CLIs, and agy-staff's answers to the shared lifecycle problems were only written in agy terms.

Design

• Ground truth and best practice only. DESIGN.md contains no issue numbers, version numbers or change history. Each rule states its reason in terms of what the host, the worker or the user needs.
• Two core ideas: design the CLI for a model as its caller, and disclose progressively from skill instructions through runtime information.
• Portable. agy appears only as the reference implementation in the opening paragraph. Concrete commands, flags and defaults stay in REFERENCE.md.
• Capabilities, not special cases. Section 11, "What depends on the worker CLI", lists each capability a worker CLI may offer, what it is used for, and how the tool degrades without it. It ends with a probe step: read the CLI's help, then make one cheap headless call with the user's consent before building on it.
• Sections: the problem and two ideas; roles; architecture; progressive disclosure; the brief and persona contracts; the job lifecycle and its exit codes; authority and the workspace; errors; state and processes; orchestration; what depends on the worker CLI; testing; non-goals.
• One state diagram. The job-lifecycle section adds a mermaid state diagram. It shows that every state other than running is final, that an expired wait leaves the job running, and that continue and restart start a new linked job. There is no architecture diagram; the README images and the section tables already cover the architecture.
• Its own README section. "Core design" keeps describing how agy-staff behaves. The new section is for people building a tool for another CLI, and it has its own anchor for sharing. Its prompt asks the agent to read the raw DESIGN.md, map the CLI's --help to section 11, list unsupported principles before writing code, and ask before any call that spends model quota. The prompt stays in English in both READMEs, like the install prompt. The Chinese README notes that DESIGN.md is in English.

Verification

• npm run check:skills: Pi and OpenCode generated skills are unchanged.
• npm pack --dry-run: docs/DESIGN.md is not packed. Installed plugins on Claude Code, Codex, Pi and OpenCode are unchanged.
• git diff --check passed.
• I cross-checked each principle against REFERENCE.md, the skills and the templates. DESIGN.md describes current behavior only.

Release

No version bump. Only documentation outside the npm files list changes. The README prompt reads DESIGN.md from GitHub master, so it takes effect on merge.

🤖 Generated with Claude Code