Skip to content

docs: lead with the agent, demote deterministic-CLI from headline framing#67

Merged
nahiyankhan merged 1 commit intomainfrom
docs/agent-led-framing
Apr 29, 2026
Merged

docs: lead with the agent, demote deterministic-CLI from headline framing#67
nahiyankhan merged 1 commit intomainfrom
docs/agent-led-framing

Conversation

@nahiyankhan
Copy link
Copy Markdown
Collaborator

Summary

  • Reframe Ghost's positioning across CLAUDE.md, README, docs site, three skill bundles (ghost-drift, ghost-expression, ghost-fleet), and map.md so agents loading the project context lead with the right mental model: agents ship UI; it drifts; Ghost is the layer that gives them a canonical design language to follow.
  • The "deterministic CLI + judgement in skills" dichotomy moves from headline copy to a footnote that points at INVARIANTS §1 and §4, where the underlying constraint actually lives. No architectural changes — every CLI verb is still pure, every recipe still runs in the host agent.
  • Skill-bundle preambles now address the agent directly ("you do the reading, deciding, and writing; the CLI is the calculator you reach for") instead of editorializing on Ghost's CLI/LLM split.
  • Patch-bumps ghost-drift and ghost-expression since their skill bundles are user-visible (changeset included).

The motivation: agents kept parroting "deterministic CLI" back as if it were the headline, because it was the first thing they read. The architecture is sound — the framing was over-indexed on the substrate and undersold the agent-native ethos.

Test plan

  • CI: pnpm check (biome, typecheck, file-sizes, docs frontmatter, cli-manifest) + pnpm test + pnpm build
  • Visual: skim docs site (/, /docs/getting-started, /docs/cli, /tools/map, /tools/fleet) for any awkward residual phrasing
  • Read installed .claude/skills/ghost-drift/SKILL.md and .claude/skills/ghost-expression/SKILL.md end-to-end as if loading them cold

🤖 Generated with Claude Code

…ming

Across CLAUDE.md, README, docs site, skill bundles, and map.md, reframe
Ghost as the design-language layer agents reach into when the UI they
generate drifts. The "deterministic CLI + judgement in skills" dichotomy
stays in INVARIANTS §1/§4 as the underlying constraint, not the headline.

Architecture is unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@nahiyankhan nahiyankhan merged commit 2c5754b into main Apr 29, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant