mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
chore(truthmark): sync structure guidance, generated surfaces, and truth docs
This commit is contained in:
MerlinH
@@ -36,7 +36,7 @@ The durable surfaces are ordinary repository files:
|
||||
- canonical docs under `docs/`
|
||||
- the managed Truthmark block inside [AGENTS.md](../../AGENTS.md)
|
||||
- the generated Codex Truth Structure, Truth Sync, Truth Realize, and Truth Check skills under `.codex/skills/`
|
||||
- the generated OpenCode Truth Structure, Truth Sync, Truth Realize, and Truth Check skills under `skills/` and `.opencode/skills/`
|
||||
- the generated OpenCode Truth Structure, Truth Sync, Truth Realize, and Truth Check skills under `.opencode/skills/`
|
||||
- configured platform instruction files such as [AGENTS.md](../../AGENTS.md), `CLAUDE.md`, `.cursor/rules/truthmark.mdc`, `.github/copilot-instructions.md`, and `GEMINI.md`
|
||||
- Gemini custom command surfaces under `.gemini/commands/truthmark/*.toml`
|
||||
|
||||
@@ -74,7 +74,7 @@ Key implementation surfaces:
|
||||
Truthmark also contains support primitives for the installed Truth Structure, Truth Sync, Truth Realize, and Truth Check workflows:
|
||||
|
||||
- `src/agents/*` renders the installed instruction text used in the managed AGENTS block
|
||||
- `src/templates/codex-skills.ts` renders the generated Codex skills and repo-local skills for explicit workflow invocation
|
||||
- `src/templates/codex-skills.ts` renders the generated Codex and OpenCode skills for explicit workflow invocation
|
||||
- `src/sync/*` classifies functional-code paths and renders Truth Sync reports
|
||||
- `src/realize/report.ts` renders the Truth Realize completion report shape
|
||||
|
||||
|
||||
@@ -111,6 +111,7 @@ When `--stdout` is used, `data` also includes:
|
||||
The command emits `action` diagnostics describing whether each scaffolded file was created, updated, or unchanged. Generated realization skill files use the `realization` diagnostic category.
|
||||
|
||||
`truthmark init` requires an existing valid `.truthmark/config.yml`. It does not create config; `truthmark config` is the required first step in a new repository.
|
||||
Configured `instruction_targets` are generated or refreshed independently of platform-specific surfaces, so `AGENTS.md` remains managed even when `claude-code` is not in `platforms`.
|
||||
|
||||
Generated Truth Structure, Truth Sync, and Truth Check surfaces and the managed `AGENTS.md` block use the `truth-sync` diagnostic category.
|
||||
|
||||
@@ -118,20 +119,16 @@ Current agent-native scaffold targets include:
|
||||
|
||||
- `.codex/skills/truthmark-structure/SKILL.md`
|
||||
- `.codex/skills/truthmark-structure/agents/openai.yaml`
|
||||
- `skills/truthmark-structure/SKILL.md`
|
||||
- `.codex/skills/truthmark-sync/SKILL.md`
|
||||
- `.codex/skills/truthmark-sync/agents/openai.yaml`
|
||||
- `skills/truthmark-sync/SKILL.md`
|
||||
- `.codex/skills/truthmark-realize/SKILL.md`
|
||||
- `.codex/skills/truthmark-realize/agents/openai.yaml`
|
||||
- `skills/truthmark-realize/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/agents/openai.yaml`
|
||||
- `.opencode/skills/truthmark-structure/SKILL.md`
|
||||
- `.opencode/skills/truthmark-sync/SKILL.md`
|
||||
- `.opencode/skills/truthmark-realize/SKILL.md`
|
||||
- `.opencode/skills/truthmark-check/SKILL.md`
|
||||
- `skills/truthmark-check/SKILL.md`
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `.cursor/rules/truthmark.mdc`
|
||||
@@ -142,7 +139,7 @@ Current agent-native scaffold targets include:
|
||||
- `.gemini/commands/truthmark/realize.toml`
|
||||
- `.gemini/commands/truthmark/check.toml`
|
||||
|
||||
Generated `SKILL.md` files use closed YAML frontmatter with `name`, `description`, `argument-hint`, `user-invocable`, and `truthmark-version` fields so Codex-style skill indexers can parse every generated workflow surface. Generated Codex metadata includes a `truthmark.version` marker plus `truthmark.refresh_command: "truthmark init"`. Generated Gemini command files use project-scoped TOML custom commands so `truthmark init` can install `/truthmark:structure`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` alongside `GEMINI.md`. Re-running `truthmark init` after a package upgrade refreshes configured committed surfaces and exposes staleness through ordinary Git diffs. Removing a platform from config stops future refreshes for that platform; it does not delete previously generated files.
|
||||
Generated `SKILL.md` files use closed YAML frontmatter with `name`, `description`, `argument-hint`, `user-invocable`, and `truthmark-version` fields so Codex-style skill indexers can parse every generated workflow surface. Generated Codex metadata includes a `truthmark.version` marker plus `truthmark.refresh_command: "truthmark init"`. Managed instruction blocks and `TRUTHMARK.md` also render the Truthmark package version, and `package.json` is the single maintained version source for those markers. Generated Gemini command files use project-scoped TOML custom commands so `truthmark init` can install `/truthmark:structure`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` alongside `GEMINI.md`. Re-running `truthmark init` after a package upgrade refreshes configured committed surfaces and exposes staleness through ordinary Git diffs. Removing a platform from config stops future refreshes for that platform; it does not delete previously generated files.
|
||||
|
||||
## Check Result Data
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ This document describes the current behavior of `truthmark config` and `truthmar
|
||||
3. creates default standards only when they are missing or empty
|
||||
4. creates missing configured docs and routing structure such as [TRUTHMARK.md](../../TRUTHMARK.md), the configured root route index, the configured default child route file, the configured feature-root README, a default area index README, and a default bounded leaf truth doc
|
||||
5. loads the configured `platforms` list
|
||||
6. writes or refreshes only the configured platform surfaces
|
||||
6. writes or refreshes configured instruction targets and configured platform surfaces
|
||||
7. rewrites managed Truthmark instruction blocks while preserving manual content outside those blocks
|
||||
8. writes generated skill surfaces for configured skill-based platforms
|
||||
9. reports migration risks instead of moving existing truth docs when hierarchy changes imply manual migration
|
||||
@@ -50,20 +50,16 @@ Current scaffold targets:
|
||||
- [CLAUDE.md](../../CLAUDE.md)
|
||||
- `.codex/skills/truthmark-structure/SKILL.md`
|
||||
- `.codex/skills/truthmark-structure/agents/openai.yaml`
|
||||
- `skills/truthmark-structure/SKILL.md`
|
||||
- `.codex/skills/truthmark-sync/SKILL.md`
|
||||
- `.codex/skills/truthmark-sync/agents/openai.yaml`
|
||||
- `skills/truthmark-sync/SKILL.md`
|
||||
- `.codex/skills/truthmark-realize/SKILL.md`
|
||||
- `.codex/skills/truthmark-realize/agents/openai.yaml`
|
||||
- `skills/truthmark-realize/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/agents/openai.yaml`
|
||||
- `.opencode/skills/truthmark-structure/SKILL.md`
|
||||
- `.opencode/skills/truthmark-sync/SKILL.md`
|
||||
- `.opencode/skills/truthmark-realize/SKILL.md`
|
||||
- `.opencode/skills/truthmark-check/SKILL.md`
|
||||
- `skills/truthmark-check/SKILL.md`
|
||||
- `.cursor/rules/truthmark.mdc`
|
||||
- `.github/copilot-instructions.md`
|
||||
- `GEMINI.md`
|
||||
@@ -72,11 +68,12 @@ Current scaffold targets:
|
||||
- `.gemini/commands/truthmark/realize.toml`
|
||||
- `.gemini/commands/truthmark/check.toml`
|
||||
|
||||
`platforms` controls which platform surfaces are written or refreshed. Defaults are `codex`, `opencode`, and `claude-code`. Teams may add `cursor`, `github-copilot`, or `gemini-cli` and rerun `truthmark init` to add those files. Gemini installs both `GEMINI.md` and project-scoped TOML commands under `.gemini/commands/truthmark/`, which surface as `/truthmark:structure`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` in Gemini CLI. Unknown platform names are config errors. Removing a platform stops future refreshes for that platform, but `init` does not delete previously generated files.
|
||||
`instruction_targets` controls shared managed-instruction files such as `AGENTS.md`. These targets are written or refreshed whenever `truthmark init` runs with a valid config, independent of the configured platform list.
|
||||
`platforms` controls which platform-specific surfaces are written or refreshed. Defaults are `codex`, `opencode`, and `claude-code`. Teams may add `cursor`, `github-copilot`, or `gemini-cli` and rerun `truthmark init` to add those files. Gemini installs both `GEMINI.md` and project-scoped TOML commands under `.gemini/commands/truthmark/`, which surface as `/truthmark:structure`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` in Gemini CLI. Unknown platform names are config errors. Removing a platform stops future refreshes for that platform, but `init` does not delete previously generated files.
|
||||
|
||||
`ensureRepoFile` is intentionally conservative: existing non-empty files are left alone. The AGENTS managed block is the exception because Truthmark owns that block and may refresh it to match current template behavior.
|
||||
|
||||
The generated Truth Structure, Truth Sync, Truth Realize, and Truth Check explicit surfaces are also managed by Truthmark and may be refreshed on rerun so the Codex skills, metadata, and repo-local skills keep matching the installed workflow contract. Generated skills and Codex metadata include the Truthmark package version that rendered them; after upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
The generated Truth Structure, Truth Sync, Truth Realize, and Truth Check explicit surfaces are also managed by Truthmark and may be refreshed on rerun so the Codex skills, metadata, and OpenCode skills keep matching the installed workflow contract. Generated skills, Codex metadata, managed instruction blocks, and `TRUTHMARK.md` include the Truthmark package version that rendered them; `package.json` is the single maintained version source. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
|
||||
## AGENTS Management Rules
|
||||
|
||||
@@ -91,7 +88,7 @@ The current managed-instruction update behavior is:
|
||||
|
||||
Repository-specific instructions should therefore live outside the managed block.
|
||||
|
||||
Truthmark does not create `OPENCODE.md` in V1. OpenCode-compatible behavior is installed through shared `AGENTS.md` guidance and repo-local skill files under `skills/` and `.opencode/skills/`.
|
||||
Truthmark does not create `OPENCODE.md` in V1. OpenCode-compatible behavior is installed through shared `AGENTS.md` guidance and project skill files under `.opencode/skills/`.
|
||||
|
||||
## Hierarchy Behavior
|
||||
|
||||
@@ -115,6 +112,7 @@ Important current defaults:
|
||||
- default code surface in the scaffolded root and child route files starts as `src/**`
|
||||
- default feature scaffolding creates an index at `<feature-root>/README.md`, an index at `<feature-root>/<default-area>/README.md`, and a bounded leaf truth doc at `<feature-root>/<default-area>/overview.md`
|
||||
- default platforms are `codex`, `opencode`, and `claude-code`
|
||||
- shared instruction targets are refreshed independently of platform-specific surfaces
|
||||
- explicit Truth Structure, Truth Sync, Truth Realize, and Truth Check surfaces are installed only for configured platforms
|
||||
- installed workflows are agent-native; generated skills tell agents to inspect the checkout directly
|
||||
- generated workflow surfaces leave Truth Sync subagent selection to the acting agent and host environment
|
||||
@@ -145,7 +143,7 @@ Current init JSON reporting uses:
|
||||
- `truthmark config` owns the committed layout contract and must happen before `truthmark init`.
|
||||
- Hierarchical routing is the only scaffold model, and route ownership stays in Markdown route files rather than config.
|
||||
- Init reports migration risk instead of rewriting existing truth doc placement on the user's behalf.
|
||||
- V1 uses shared `AGENTS.md` plus generated skill or command surfaces for host compatibility instead of creating host-specific top-level instruction files for every adapter.
|
||||
- V1 uses configured shared instruction targets such as `AGENTS.md` plus generated skill or command surfaces for host compatibility instead of creating host-specific top-level instruction files for every adapter.
|
||||
|
||||
## Rationale
|
||||
|
||||
|
||||
@@ -52,9 +52,10 @@ Workflow invocation examples:
|
||||
|
||||
The managed `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and equivalent platform instruction blocks keep compact reminders for these workflows. They intentionally omit report examples and long procedural checklists so installed prompts do not consume unnecessary model context. The generated skills and Gemini command files hold the detailed workflow bodies and report examples for explicit invocation.
|
||||
|
||||
Generated skill files, Gemini command files, and Codex metadata include the Truthmark package version used to render them. After upgrading Truthmark, rerun `truthmark init` and review the generated workflow diffs. This rerun-init convention is the V1 staleness story for committed workflow surfaces.
|
||||
Generated skill files, Gemini command files, Codex metadata, managed instruction blocks, and `TRUTHMARK.md` include the Truthmark package version used to render them. The package version in `package.json` is the single maintained version source. After upgrading Truthmark, rerun `truthmark init` and review the generated workflow diffs. This rerun-init convention is the V1 staleness story for committed workflow surfaces.
|
||||
|
||||
Generated workflow surfaces include the configured hierarchy summary from `.truthmark/config.yml`. Agents must read the configured root route index and only relevant child route files before updating routed truth docs. Generated skill text states that repository docs and code are inspected evidence, not executable instruction authority.
|
||||
Truthmark-owned skill surfaces are generated under host-specific directories such as `.codex/skills/` and `.opencode/skills/`. Repo-root `skills/` files are not generated workflow surfaces and are not classified as derived Truthmark output.
|
||||
Generated workflow text also treats feature `README.md` files as indexes rather than Truth Sync targets. Current behavior truth should live in bounded leaf docs under the configured feature root, such as `<feature-root>/<domain>/<behavior>.md`.
|
||||
|
||||
## Truth Structure
|
||||
@@ -68,6 +69,9 @@ The agent should:
|
||||
- define areas by product or behavior ownership
|
||||
- repair broad, stale, missing, or non-canonical routing
|
||||
- create starter canonical truth docs when useful
|
||||
- write starter truth docs with closed YAML frontmatter bounded by opening and closing `---` lines, including `status`, `doc_type`, `last_reviewed`, and `source_of_truth` inside that frontmatter
|
||||
- include `Product Decisions` and `Rationale` sections in starter truth docs
|
||||
- repair routed canonical current-truth docs that are missing `Product Decisions` or `Rationale` sections before finishing topology repair
|
||||
- keep starter truth docs inside canonical current-truth destinations
|
||||
- keep feature `README.md` files as indexes and create bounded leaf docs for behavior truth
|
||||
- keep feature docs behavior-oriented rather than endpoint-oriented
|
||||
@@ -168,11 +172,13 @@ Truthmark currently provides installed workflow text, generated Codex and OpenCo
|
||||
- Gemini CLI uses generated `.gemini/commands/truthmark/*.toml` files for explicit workflow entrypoints because its native host surface is namespaced custom commands rather than `SKILL.md`.
|
||||
- Generated workflow surfaces must render the configured hierarchy and decision-truth guidance once because those surfaces shape future agent behavior.
|
||||
- Truth Structure owns AI-native topology governance so large repositories do not depend on humans manually organizing `docs/features`.
|
||||
- Truth Structure must satisfy canonical decision-section expectations for both new starter docs and repaired routed docs; `doc-structure` review diagnostics are a signal for topology repair, not only a separate checker concern.
|
||||
- Truth Sync must not worsen weak topology by adding generic feature docs behind broad catch-all routing.
|
||||
- Feature `README.md` files are indexes; bounded leaf docs are the normal Truth Sync targets for current behavior.
|
||||
- Truth Sync delegation is host-owned: generated workflow surfaces may describe when delegation is allowed, but must not name a preferred subagent or project-local subagent preference file.
|
||||
- Active decisions belong in the canonical doc they govern. Short inline decision dates are allowed, but workflow text should reject separate ADR-style drift.
|
||||
- Direct checkout inspection is the workflow authority. `truthmark check` may validate artifacts after or around agent work, but installed workflows must not require a helper payload before acting.
|
||||
- Truthmark follows current host discovery paths for generated skills: Codex uses `.codex/skills/`, OpenCode uses `.opencode/skills/`, and repo-root `skills/` is not a generated V1 target.
|
||||
|
||||
## Rationale
|
||||
|
||||
@@ -182,6 +188,8 @@ Rejecting helper-payload dependency preserves the product boundary from the agen
|
||||
|
||||
Putting topology governance in installed workflow text keeps the large-repository behavior portable to AI environments that have repository access and agents but do not have the Truthmark binary installed.
|
||||
|
||||
Requiring Truth Structure to add missing decision-section headings keeps repair output aligned with `truthmark check` without weakening the checker's canonical-doc quality signal.
|
||||
|
||||
## Primary Code Files
|
||||
|
||||
- `src/agents/instructions.ts`
|
||||
|
||||
@@ -30,7 +30,7 @@ Treat [AGENTS.md](../../AGENTS.md) as two surfaces:
|
||||
|
||||
Do not hand-edit the managed block for one-off wording changes. Change the template source instead, then refresh the block through the normal workflow.
|
||||
|
||||
Generated Truthmark skill files under `.codex/skills/` and `skills/` follow the same rule. Edit the renderers in `src/agents/` and `src/templates/`, then refresh through `truthmark init`.
|
||||
Generated Truthmark skill files under `.codex/skills/` and `.opencode/skills/` follow the same rule. Edit the renderers in `src/agents/` and `src/templates/`, then refresh through `truthmark init`.
|
||||
|
||||
## Maintaining docs/truthmark/areas.md
|
||||
|
||||
|
||||
Reference in New Issue
Block a user