b38cfac760
Moves all Mosaic framework runtime files from the separate bootstrap repo into the monorepo as canonical source. The @mosaic/mosaic npm package now ships the complete framework — bin scripts, runtime configs, tools, and templates — enabling standalone installation via npm install. Structure: packages/mosaic/framework/ ├── bin/ 28 CLI scripts (mosaic, mosaic-doctor, mosaic-sync-skills, etc.) ├── runtime/ Runtime adapters (claude, codex, opencode, pi, mcp) ├── tools/ Shell tooling (git, prdy, orchestrator, quality, etc.) ├── templates/ Agent and repo templates ├── defaults/ Default identity files (AGENTS.md, STANDARDS.md, SOUL.md, etc.) ├── install.sh Legacy bash installer └── remote-install.sh One-liner remote installer Key files with Pi support and recent fixes: - bin/mosaic: launch_pi() with skills-local loop - bin/mosaic-doctor: --fix auto-wiring for all 4 harnesses - bin/mosaic-sync-skills: Pi as 4th link target, symlink-aware find - bin/mosaic-link-runtime-assets: Pi settings.json patching - bin/mosaic-migrate-local-skills: Pi skill roots, symlink find - runtime/pi/RUNTIME.md + mosaic-extension.ts Package ships 251 framework files in the npm tarball (278KB compressed).
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# Agent Configuration Specification v1.0
|
|
|
|
> Defines what "well-configured" means for AI agent development across all coding projects.
|
|
|
|
## Runtime Context File — Required Sections
|
|
|
|
### Tier 1 (Required — blocks audit pass)
|
|
|
|
1. **Conditional Documentation Loading** — Table linking to `~/.config/mosaic/guides/`
|
|
2. **Quality Gates** — Bash commands that must pass before commit (build, test, lint, typecheck)
|
|
3. **Build/Test/Lint commands** — How to build, test, and lint the project
|
|
|
|
### Tier 2 (Recommended — logged as warning)
|
|
|
|
4. Technology Stack table
|
|
5. Repository Structure tree
|
|
6. Commit format reference
|
|
7. Secrets management note
|
|
8. Multi-agent coordination note
|
|
9. **Campsite Rule** — "Touching it makes it yours" policy for code violations
|
|
|
|
### Tier 3 (Optional — nice to have)
|
|
|
|
10. Code Review section (Codex commands)
|
|
11. Issue Tracking workflow
|
|
12. Session Protocol (start/end)
|
|
|
|
## AGENTS.md — Required Sections
|
|
|
|
### Tier 1 (Required)
|
|
|
|
1. **Codebase Patterns** — At least one entry or placeholder with instructive comments
|
|
2. **Common Gotchas** — At least one entry or placeholder with instructive comments
|
|
3. **Quality Gates** — Duplicated for quick agent reference
|
|
|
|
### Tier 2 (Recommended)
|
|
|
|
4. Key Files table
|
|
5. Testing Approaches section
|
|
|
|
## Monorepo Sub-AGENTS.md
|
|
|
|
Required in any directory under `apps/`, `packages/`, `services/`, or `plugins/`
|
|
that contains its own `package.json` or `pyproject.toml`.
|
|
|
|
Minimum content:
|
|
|
|
1. Purpose (one line)
|
|
2. Patterns (at least placeholder)
|
|
3. Gotchas (at least placeholder)
|
|
|
|
## Detection Markers
|
|
|
|
The `agent-lint.sh` tool checks for these markers:
|
|
|
|
| Check | Pass Criteria |
|
|
| --------------------------- | -------------------------------------------------------------------------------------------- |
|
|
| Runtime context file exists | `CLAUDE.md` or `RUNTIME.md` present at project root |
|
|
| AGENTS.md exists | File present at project root |
|
|
| Conditional context/loading | Runtime context file contains `~/.config/mosaic/guides` or `Conditional` + `Loading/Context` |
|
|
| Quality gates | Runtime context file contains `Quality Gates` or quality commands (test, lint, typecheck) |
|
|
| Monorepo sub-agents | Each app/package dir with own manifest has AGENTS.md |
|
|
|
|
## Fragment Sources
|
|
|
|
Shared sections are maintained in `~/.config/mosaic/templates/agent/fragments/`:
|
|
|
|
| Fragment | Injects Section |
|
|
| ------------------------ | ---------------------------------------- |
|
|
| `conditional-loading.md` | Conditional Documentation Loading table |
|
|
| `commit-format.md` | Commit format convention |
|
|
| `secrets.md` | Secrets management note |
|
|
| `multi-agent.md` | Multi-agent coordination protocol |
|
|
| `code-review.md` | Code review commands |
|
|
| `campsite-rule.md` | Campsite Rule — fix violations you touch |
|