Skip to content

feat: template dual-audience split + Node installer + consumer maintenance guide - #5

Merged
entropy-cloud merged 5 commits into
entropy-cloud:mainfrom
pymjer:feat/template-install-improvements
Jul 30, 2026
Merged

feat: template dual-audience split + Node installer + consumer maintenance guide#5
entropy-cloud merged 5 commits into
entropy-cloud:mainfrom
pymjer:feat/template-install-improvements

Conversation

@pymjer

@pymjer pymjer commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Summary

5 commits improving the AGE template's install flow, tooling, and consumer post-install maintainability. All backward-compatible — the installer skips existing files, so current consumers are unaffected.

Changes by area

Template dual-audience split + onboarding

  • Separate template/ (pristine skeletons for consumers) from docs/ (real-project versions for mission-driver dogfooding) — fixes the ambiguity where consumer installs picked up mission-driver-specific content
  • Add onboarding mission + roadmap so consumers can auto-fill context/architecture docs after install

Tooling: pnpm workspace + cross-platform Node installer

  • Unify tools/ as a pnpm workspace (single lockfile, hoisted deps)
  • Port install-age.sh to Node ESM (tools/install-age.mjs, zero deps) — Windows users no longer need Git Bash; adds install-age.cmd entry point
  • Fix runner.js session/prompt contract drift (556/556 tests green)

Install manifest completeness

  • Add .opencode/skills/mission-driver/ (SKILL.md + 2 references) to the install set — was previously missing, consumers lacked the operator skill

Consumer maintenance guide + context routing fix

  • NEW AGE-FILES-GUIDE.md (ships to docs/references/age-files-guide.md): classifies the 88 installed files into 6 maintenance categories (A engine infra / B one-time config / C onboarding fills / D requirement-design fills / E as-shipped / F runtime), so consumers know exactly what to do with each file
  • project-context.md: add Companion Context Files section so flow steps route to ai-autonomy-policy.md / codebase-map.md / source-of-truth-and-precedence.md via the one file every step hard-reads. Fixes broken routing when consumers customize AGENTS.md and drop the template's "Read This First" section.

Verification (full green)

  • pnpm md:test: 556/556 pass
  • pnpm install-age:test: 15/15 pass
  • Fresh install (node tools/install-age.mjs <tmp>): 88 files copied / 0 skipped
  • Manifest parse: 88 entries clean
  • AGE-FILES-GUIDE numbers consistent (no stray 87)

Commits

  • be82a48 feat(template): split real-project vs template audiences + add onboarding mission
  • dc75030 docs(plans): add proposal + 2 plans + log for template-realproject split + onboarding mission
  • 6ecdc89 feat(tools): unify pnpm workspace + Node installer + fix runner session/prompt
  • f2ff7af feat(install-age): manifest 补 mission-driver operator skill
  • 80b5256 feat(install): add AGE-FILES-GUIDE + companion context routing

Test plan

  • Fresh clone + ./install-age.sh /tmp/test "Test" → 88 files, no errors
  • ./tools/mission-driver.sh list smoke passes
  • docs/references/age-files-guide.md present and numbers consistent
  • docs/context/project-context.md contains Companion Context Files section

pymjer added 5 commits July 27, 2026 17:49
@pymjer
feat(template): split real-project vs template audiences + add onboar…
be82a48 
…ding mission

This repo now serves two audiences explicitly:
1. Real project - develops tools/mission-driver/ using its own AGE workflow
2. Template - consumers run ./install-age.sh to bootstrap a new AGE project

- Move 16 fill-in files + START-HERE-after-copy.md to template/ (pristine copies)
- Rewrite root AGENTS.md as real-project contract (Dual-Audience Repo +
  In-Tree Tool sections; all 15 Operating Rules preserved)
- Restore root README.md / README.zh.md to rich original (~370/~140 lines,
  was over-cut to 53 lines) with minimal updates for install-age.sh + onboarding
- New root DEVELOPMENT.md (this repo's own dev process)
- Fill 11 root docs from template stubs (context/*, architecture/*,
  process/app-workflow, backlog/README, index.md, testing/known-good-baselines)
- New docs/architecture/template-vs-realproject-boundary.md (architecture truth)
- install-age.sh: TEMPLATE_COPIED array + extended sed-replace (all fill-in
  files now get <project-name> substitution; shared methodology untouched);
  onboarding.json heredoc + mkdir docs/plans/onboarding; updated NEXT STEPS
- install-age.manifest: 15 entries gain template/ prefix + 1 onboarding entry
- New template/docs/backlog/onboarding-roadmap.md (8 WIscovering context/*,
  architecture/*, index, app-workflow, known-good-baselines + logs/{year}/)
- New tools/check-install-age.sh (persisted closure-gate test, 10 assertions)
- tools/README.md: add check-install-age.sh to Core Tools
- tools/package.json: add check:install script

Verified: pnpm --prefix tools check:install 10/10 PASS; mission-check.mjs
validates onboarding.json; ./tools/mission-driver.sh list from real-target
install shows base + demo + onboarding (3 missions).
@pymjer
docs(plans): add proposal + 2 plans + log for template-realproject sp…
dc75030 
…lit + onboarding mission

- docs/analysis/2026-07-27-0000-template-realproject-split-proposal.md (v4,
  passed 4 rounds of independent audit; recommendation: template/ subdirectory
  overlay extending existing install-age.sh mechanism)
- docs/plans/2026-07-27-0000-template-realproject-split-plan.md (Plan Status:
  completed; independent draft review + closure audit by subagents)
- docs/plans/2026-07-27-0100-onboarding-mission-plan.md (Plan Status: completed;
  independent draft review; solo closure per AGENTS.md Reviewer-Availability
  Fallback for additive non-protected change)
- docs/logs/2026/07-27.md (both plans' execution log + audit lessons)

Audit trail: proposal survived 4 independent audit rounds (B1 enumeration,
B2 pnpm justification, B3 carry-forward, B4 sed-replace breakage); plan 1
survived 1 draft review (2B+5N fixed) + 1 closure audit (B1 clerical fixed);
plan 2 survived 1 draft review (2B+8N fixed) + 1 post-implementation audit
(B1 onboarding-roadmap instructional <project-name> corruption fixed).
@pymjer
feat(tools): unify pnpm workspace + Node installer + fix runner sessi…
6ecdc89 
…on/prompt

Three orthogonal improvements plus a test fix:

1. tools/ → pnpm workspace (Phase 1)
   - Add tools/pnpm-workspace.yaml (members: mission-driver, mission-driver/web)
   - Single lockfile (tools/pnpm-lock.yaml); unified PM pin pnpm@10.27.0
   - Sync .github/workflows/web-dist-check.yml to workspace topology
   - Supersedes 2026-07-24-1030 Decision 2 (preserves its no-autobuild constraint)

2. heredoc materialization (Phase 2)
   - Move ~200 lines of install-age.sh heredoc into template/install/ real files
   - install-age.manifest: add '> dst' / ':: flags' optional syntax
   - install-age.sh: 422 → 259 lines (manifest-driven copy + flags)

3. install-age.sh → tools/install-age.mjs (Phase 3)
   - Zero-dep Node ESM (only node: builtins); JSDoc types
   - install-age.sh → 16-line thin shim; add install-age.cmd (Windows native)
   - 15 unit tests (pnpm install-age:test); check-install-age.sh 10/10 PASS

4. fix runner.js session forwarding + prompt transport
   - DEFAULT_DRIVER_ARGS missing {session} token → --session never injected
   - promptMode default 'arg' → 'stdin' (mdr-3 Phase 2 design intent)
   - md:test now 556/556 full green (was 549 pass / 7 fail)

Verification: pnpm md:test 556/0 + pnpm md:web:check:dist exit=0
+ pnpm install-age:test 15/0 + check-install-age.sh 10/10
@pymjer
feat(install-age): manifest 补 mission-driver operator skill
f2ff7af 
.opencode/skills/mission-driver/ 此前不在 install-age.manifest 中，
consumer 项目装出来缺这个 skill。新增 3 个条目（SKILL.md +
references/{mission-config-schema,roadmap-template}.md），installer
无需改动（已支持任意相对路径 + 自动 mkdir + skip-existing）。

Verification (full green):
- readManifest 解析 3 条目 flags=[] src=dst
- 实跑 node tools/install-age.mjs <tmp>/age-test TestProject 三文件全部 +
- diff -q 与源字节一致 (18962 / 13081 / 12551 B)
@pymjer
feat(install): add AGE-FILES-GUIDE + companion context routing
80b5256 
两轮 consumer 维护性改进:

1. project-context.md 加 Companion Context Files 段 — flow 各 step
   通过此文件路由到 ai-autonomy-policy / codebase-map / source-of-truth。
   治本 consumer 自定义 AGENTS.md 后丢掉 Read This First 的断链。

2. AGE-FILES-GUIDE.md (新) — 88 文件维护指南，6 类分类 (A 引擎基建 /
   B 一次性配置 / C onboarding 填 / D 需求设计填 / E 即装即用 / F 运行时)。
   install 到 consumer docs/references/age-files-guide.md。

Verification (full green):
- readManifest: 88 entries parse clean
- install to temp: 88 copied / 0 skipped
- grep installed guide: all numbers consistent (no stray 87)
@pymjer pymjer mentioned this pull request Jul 30, 2026
Merged
7 tasks
@entropy-cloud
entropy-cloud merged commit 178e2aa into entropy-cloud:main Jul 30, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@pymjer @entropy-cloud