mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
docs: align Truthmark workflow docs and skill guidance
This commit is contained in:
MerlinH
+28
-156
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: agent-rules
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-10
|
||||
source_of_truth:
|
||||
- ../../AGENTS.md
|
||||
- ../README.md
|
||||
@@ -10,179 +10,51 @@ source_of_truth:
|
||||
|
||||
# Repository Rules
|
||||
|
||||
## Scope
|
||||
Repository-wide agent authority, routing, and completion rules. Prefer the smallest sufficient read; detailed behavior lives in [docs/](../README.md).
|
||||
|
||||
This document defines repository-wide agent rules, authority order, and completion requirements for Truthmark.
|
||||
## Authority
|
||||
|
||||
Detailed standards, current architecture, contracts, and current feature behavior live under [docs/](../README.md).
|
||||
|
||||
## Authority and Context
|
||||
|
||||
### Authority Order
|
||||
|
||||
When sources conflict, authority descends in this order:
|
||||
Conflict order:
|
||||
|
||||
1. this file
|
||||
2. [TRUTHMARK.md](../../TRUTHMARK.md)
|
||||
3. [docs/truthmark/areas.md](../truthmark/areas.md)
|
||||
3. [docs/truthmark/areas.md](../truthmark/areas.md) and `docs/truthmark/areas/**/*.md`
|
||||
4. `docs/standards/**/*.md`
|
||||
5. `docs/architecture/**/*.md`
|
||||
6. `docs/features/**/*.md`
|
||||
|
||||
[README.md](../../README.md) may help with onboarding and positioning context, but it does not override the canonical current-state docs above.
|
||||
Authoritative context is the current checkout plus user-provided session context; chat, external notes, and off-repo memory are non-authoritative unless committed or supplied now.
|
||||
|
||||
### Context Boundaries
|
||||
Code is the implementation. On code/doc conflict, inspect code, decide whether code is intentional or docs are stale, update stale docs for intentional behavior, and change code to match docs only when requested or clearly required.
|
||||
|
||||
Authoritative context is limited to committed repository artifacts plus user-provided session context:
|
||||
## Product Boundary
|
||||
|
||||
- code
|
||||
- docs
|
||||
- tests
|
||||
- config
|
||||
- generated artifacts that are checked into the repo intentionally
|
||||
Truthmark is a local-first Node/TypeScript repository truth protocol. CLI commands are `config`, `init`, and `check`; Truth Structure, Truth Sync, Truth Realize, and Truth Check are installed workflow surfaces, not CLI commands. Runtime is installed `SKILL.md` files plus the managed `AGENTS.md` block. `config` writes `.truthmark/config.yml` (`platforms` selects agent surfaces), `init` installs or refreshes surfaces, and `check` validates truth artifacts. Agents inspect the active worktree directly. No daemon, database, remote service, or V1 MCP server.
|
||||
|
||||
Treat chat history, external notes, and off-repo memories as non-authoritative unless the user provides them in the current session or the information has been committed into the repository.
|
||||
## Rules
|
||||
|
||||
### Code-vs-Docs Rule
|
||||
1. Branch-local Markdown is canonical; the current checkout is the truth boundary.
|
||||
2. Current truth belongs in canonical docs, not historical plans or separate timestamped decision logs.
|
||||
3. Active decisions and rationale live in the canonical doc for the governed behavior.
|
||||
4. The `AGENTS.md` Truthmark block is generated; edit templates, not the managed block, unless explicitly maintaining the generated surface.
|
||||
5. Document implemented V1 behavior only; do not add speculative commands, services, or capabilities.
|
||||
6. Keep routing explicit: when a code area changes canonical docs, update truth routing in the same change.
|
||||
7. Behavior, contract, workflow, and completion-rule changes update the nearest canonical doc; major product/onboarding/install/command/positioning/workflow changes also review the root README and localized variants.
|
||||
8. Follow established module boundaries; avoid duplicate surfaces, single-use abstractions, speculative configurability, and impossible-scenario error handling.
|
||||
9. Use [testing-and-verification.md](../standards/testing-and-verification.md) and [pre-completion-checklist.md](../standards/pre-completion-checklist.md); define success criteria and loop until verified or blocked.
|
||||
10. Work surgically: surface material assumptions or ambiguity, touch only request-traceable lines, match existing style, clean up only artifacts made unused by the current change, and report unrelated issues instead of editing them.
|
||||
|
||||
Code is the current implementation.
|
||||
## Routing
|
||||
|
||||
If code and docs conflict:
|
||||
When unfamiliar, start with [docs/README.md](../README.md), [overview.md](../architecture/overview.md), [module-map.md](../architecture/module-map.md), and [contracts.md](../features/contracts.md).
|
||||
|
||||
1. inspect the relevant code path
|
||||
2. determine whether the code is intentional or the doc is stale
|
||||
3. update the stale doc when behavior is intentional
|
||||
4. only change code to match docs when the user explicitly wants that outcome or the docs clearly reflect the intended requirement
|
||||
- CLI/scaffold: [init-and-scaffold.md](../features/init-and-scaffold.md), [contracts.md](../features/contracts.md), plus [maintaining-repository-truth.md](../standards/maintaining-repository-truth.md) for docs placement or AGENTS management; new repos run `truthmark config` before `truthmark init`.
|
||||
- Check/routing/validation: [check-diagnostics.md](../features/check-diagnostics.md), [documentation-governance.md](../standards/documentation-governance.md), [contracts.md](../features/contracts.md).
|
||||
- Workflows/reporting: [TRUTHMARK.md](../../TRUTHMARK.md), [installed-workflows.md](../features/installed-workflows.md), plus [maintaining-repository-truth.md](../standards/maintaining-repository-truth.md) for routing or canonical doc placement.
|
||||
- Docs organization: [docs/README.md](../README.md), [documentation-governance.md](../standards/documentation-governance.md), [maintaining-repository-truth.md](../standards/maintaining-repository-truth.md).
|
||||
|
||||
## Project Intent
|
||||
|
||||
Truthmark is an agent-native repository truth protocol packaged with a local-first Node and TypeScript installer and validator.
|
||||
|
||||
Current product boundaries:
|
||||
|
||||
- user-facing CLI commands are `config`, `init`, and `check`
|
||||
- installed `SKILL.md` files and the managed `AGENTS.md` block are the runtime for truth workflows
|
||||
- Truth Structure, Truth Sync, Truth Realize, and Truth Check are installed workflow surfaces, not top-level CLI commands
|
||||
- `truthmark config` writes the committed hierarchy contract before workflow installation
|
||||
- `.truthmark/config.yml` `platforms` controls which agent harness surfaces `truthmark init` installs or refreshes
|
||||
- agents inspect the checkout directly and make semantic judgments about area structure, routing, sync, realization, and truth health
|
||||
- `truthmark init` installs or refreshes workflow surfaces
|
||||
- `truthmark check` validates repository truth artifacts after agent work
|
||||
- the tool operates on the active Git worktree and does not require a daemon, database, or remote service
|
||||
- V1 does not ship an MCP server
|
||||
|
||||
## Non-Negotiable Rules
|
||||
|
||||
1. **Branch-local Markdown is canonical**
|
||||
- The current checkout is the truth boundary.
|
||||
|
||||
2. **Keep current truth separate from history**
|
||||
- Current behavior belongs in configured canonical roots such as `docs/architecture/**` and `docs/features/**`.
|
||||
- Historical planning artifacts do not become current truth automatically; rewrite current decisions into the canonical docs they govern.
|
||||
|
||||
3. **Keep active decisions in canonical docs**
|
||||
- Active decisions and rationale belong in the same canonical doc as the behavior they govern.
|
||||
- Short inline decision dates are allowed; do not create separate timestamped decision-ticket folders for current decisions.
|
||||
|
||||
4. **The managed Truthmark block stays managed**
|
||||
- The block in [AGENTS.md](../../AGENTS.md) between `<!-- truthmark:start -->` and `<!-- truthmark:end -->` is a generated surface.
|
||||
- Manual repository-specific guidance belongs outside that block.
|
||||
|
||||
5. **Document actual V1 behavior only**
|
||||
- Do not add speculative CLI commands, hosted services, or product capabilities that are not implemented.
|
||||
|
||||
6. **Areas routing must stay explicit**
|
||||
- If the canonical docs for a code area change, update [docs/truthmark/areas.md](../truthmark/areas.md) in the same change.
|
||||
|
||||
7. **Docs change with behavior**
|
||||
- If a behavior, contract, workflow, or completion rule changes, update the nearest canonical doc in the same working change.
|
||||
- For major product, onboarding, install, command, positioning, or workflow changes, review the root [README.md](../../README.md) in the same working change and update stale user-facing claims, examples, or command sequences.
|
||||
- When the root README changes materially, update the localized README variants in the same working change or explicitly confirm why they remain intentionally different.
|
||||
|
||||
8. **Keep onboarding honest**
|
||||
- The root README is not the canonical behavior spec, but it is the human entry point. It must not lag behind major product changes that affect how people understand, install, or use Truthmark.
|
||||
|
||||
9. **Prefer established module boundaries**
|
||||
- Follow the current directory responsibilities before introducing new abstractions or duplicate surfaces.
|
||||
|
||||
10. **Testing policy is centralized**
|
||||
- Follow [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md) for commands.
|
||||
|
||||
11. **Completion policy is centralized**
|
||||
- Use [docs/standards/pre-completion-checklist.md](../standards/pre-completion-checklist.md) as the completion gate.
|
||||
|
||||
12. **Scope changes narrowly**
|
||||
- Do not mix unrelated refactors or speculative cleanup into a focused task.
|
||||
|
||||
## Documentation Routing
|
||||
|
||||
Start here when working in an unfamiliar area:
|
||||
|
||||
- [docs/README.md](../README.md)
|
||||
- [docs/architecture/overview.md](../architecture/overview.md)
|
||||
- [docs/architecture/module-map.md](../architecture/module-map.md)
|
||||
- [docs/features/contracts.md](../features/contracts.md)
|
||||
|
||||
### CLI or scaffold changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [docs/features/init-and-scaffold.md](../features/init-and-scaffold.md)
|
||||
2. [docs/features/contracts.md](../features/contracts.md)
|
||||
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md) when the change affects docs placement or AGENTS management
|
||||
|
||||
Run `truthmark config` before `truthmark init` in new repositories so teams can review the hierarchy before generated agent behavior is installed.
|
||||
|
||||
### Check, routing, or validation changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [docs/features/check-diagnostics.md](../features/check-diagnostics.md)
|
||||
2. [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
|
||||
3. [docs/features/contracts.md](../features/contracts.md)
|
||||
|
||||
### Installed workflow or reporting changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [TRUTHMARK.md](../../TRUTHMARK.md)
|
||||
2. [docs/features/installed-workflows.md](../features/installed-workflows.md)
|
||||
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md) if routing or canonical docs placement changes
|
||||
|
||||
### Documentation-only organization changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [docs/README.md](../README.md)
|
||||
2. [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
|
||||
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
|
||||
|
||||
## Guardrails
|
||||
|
||||
### Anti-drift rules
|
||||
|
||||
- do not create a shadow documentation tree
|
||||
- do not treat historical plans as current implementation docs
|
||||
- do not keep editing the managed Truthmark block manually unless the template behavior itself is changing
|
||||
- do not broaden current-state docs with draft or aspirational behavior
|
||||
- do not leave doc routing ambiguous when code moves or new code surfaces are added
|
||||
- do not finish a major product or workflow change without checking whether the root README still tells the truth
|
||||
|
||||
### Divergence rule
|
||||
|
||||
When several files follow an established pattern and one diverges, assume the diverging file needs justification before copying it.
|
||||
|
||||
### When blocked
|
||||
|
||||
Re-read the relevant canonical docs, inspect the owning implementation, and then change approach. If the blocker remains, surface the blocker explicitly instead of guessing.
|
||||
If blocked, re-read the relevant canonical docs and owning implementation, then surface the blocker instead of guessing. When one file diverges from an established pattern, require justification before copying it.
|
||||
|
||||
## Maintenance
|
||||
|
||||
Update this file only when repository-wide agent rules change.
|
||||
|
||||
When updating it:
|
||||
|
||||
- keep it concise and policy-focused
|
||||
- move detailed procedures into standards or guides
|
||||
- keep current feature behavior in `docs/features`
|
||||
- update `last_reviewed`
|
||||
Update this file only for repository-wide agent rules. Keep it compact and policy-focused; move procedures to standards or guides, keep feature behavior in `docs/features`, and update `last_reviewed`.
|
||||
|
||||
@@ -37,7 +37,7 @@ The durable surfaces are ordinary repository files:
|
||||
- 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 `.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`
|
||||
- configured platform instruction files such as [AGENTS.md](../../AGENTS.md), `CLAUDE.md`, `.github/copilot-instructions.md`, and `GEMINI.md`
|
||||
- Gemini custom command surfaces under `.gemini/commands/truthmark/*.toml`
|
||||
|
||||
Generated workflow surfaces are committed repository files with Truthmark version markers. The V1 upgrade path is to upgrade the package, rerun `truthmark init`, and review the generated diffs.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: feature
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-10
|
||||
source_of_truth:
|
||||
- ../../src/config/schema.ts
|
||||
- ../../src/checks/check.ts
|
||||
@@ -24,7 +24,7 @@ Truthmark loads `.truthmark/config.yml` and validates it against the current sch
|
||||
Current fields:
|
||||
|
||||
- `version`: must be `1`
|
||||
- `platforms`: optional list of agent harnesses to initialize; defaults to `codex`, `opencode`, and `claude-code`
|
||||
- `platforms`: optional list of agent harnesses to initialize; defaults to all supported platforms
|
||||
- `docs.layout`: currently `hierarchical`
|
||||
- `docs.roots`: named canonical doc roots
|
||||
- `docs.routing.root_index`: root area index path
|
||||
@@ -53,7 +53,6 @@ Supported `platforms` values are:
|
||||
- `codex`
|
||||
- `opencode`
|
||||
- `claude-code`
|
||||
- `cursor`
|
||||
- `github-copilot`
|
||||
- `gemini-cli`
|
||||
|
||||
@@ -125,21 +124,28 @@ Current agent-native scaffold targets include:
|
||||
- `.codex/skills/truthmark-realize/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-check/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/agents/openai.yaml`
|
||||
- `.claude/skills/truthmark-structure/SKILL.md`
|
||||
- `.claude/skills/truthmark-sync/SKILL.md`
|
||||
- `.claude/skills/truthmark-realize/SKILL.md`
|
||||
- `.claude/skills/truthmark-check/SKILL.md`
|
||||
- `.opencode/skills/truthmark-structure/SKILL.md`
|
||||
- `.opencode/skills/truthmark-sync/SKILL.md`
|
||||
- `.opencode/skills/truthmark-realize/SKILL.md`
|
||||
- `.opencode/skills/truthmark-check/SKILL.md`
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `.cursor/rules/truthmark.mdc`
|
||||
- `.github/copilot-instructions.md`
|
||||
- `.github/prompts/truthmark-structure.prompt.md`
|
||||
- `.github/prompts/truthmark-sync.prompt.md`
|
||||
- `.github/prompts/truthmark-realize.prompt.md`
|
||||
- `.github/prompts/truthmark-check.prompt.md`
|
||||
- `GEMINI.md`
|
||||
- `.gemini/commands/truthmark/structure.toml`
|
||||
- `.gemini/commands/truthmark/sync.toml`
|
||||
- `.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"`. 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.
|
||||
Generated `SKILL.md` files use closed YAML frontmatter with `name`, `description`, `argument-hint`, `user-invocable`, and `truthmark-version` fields so Codex-style, Claude Code, and OpenCode-style skill indexers can parse every generated workflow surface. Generated Copilot prompt files use `.github/prompts/*.prompt.md` files with `agent` and `description` frontmatter so supported Copilot IDEs can expose `/truthmark-*` prompts. 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. `TRUTHMARK.md` stays a compact branch-local contract rather than a duplicate workflow procedure surface. 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
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: feature
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-10
|
||||
source_of_truth:
|
||||
- ../../src/init/init.ts
|
||||
- ../../src/templates/init-files.ts
|
||||
@@ -60,8 +60,15 @@ Current scaffold targets:
|
||||
- `.opencode/skills/truthmark-sync/SKILL.md`
|
||||
- `.opencode/skills/truthmark-realize/SKILL.md`
|
||||
- `.opencode/skills/truthmark-check/SKILL.md`
|
||||
- `.cursor/rules/truthmark.mdc`
|
||||
- `.claude/skills/truthmark-structure/SKILL.md`
|
||||
- `.claude/skills/truthmark-sync/SKILL.md`
|
||||
- `.claude/skills/truthmark-realize/SKILL.md`
|
||||
- `.claude/skills/truthmark-check/SKILL.md`
|
||||
- `.github/copilot-instructions.md`
|
||||
- `.github/prompts/truthmark-structure.prompt.md`
|
||||
- `.github/prompts/truthmark-sync.prompt.md`
|
||||
- `.github/prompts/truthmark-realize.prompt.md`
|
||||
- `.github/prompts/truthmark-check.prompt.md`
|
||||
- `GEMINI.md`
|
||||
- `.gemini/commands/truthmark/structure.toml`
|
||||
- `.gemini/commands/truthmark/sync.toml`
|
||||
@@ -69,11 +76,11 @@ Current scaffold targets:
|
||||
- `.gemini/commands/truthmark/check.toml`
|
||||
|
||||
`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.
|
||||
`platforms` controls which platform-specific surfaces are written or refreshed. Defaults include all supported platforms: `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`. Claude Code installs both `CLAUDE.md` and project skills under `.claude/skills/`, which surface as `/truthmark-structure`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check`. GitHub Copilot installs both `.github/copilot-instructions.md` and prompt files under `.github/prompts/`, which surface as `/truthmark-structure`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check` in supported Copilot IDEs. 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 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.
|
||||
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, Claude Code project skills, GitHub Copilot prompt files, and OpenCode skills keep matching the installed workflow contract. Generated skills, Codex metadata, Copilot prompt files, 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
|
||||
|
||||
@@ -83,7 +90,7 @@ The current managed-instruction update behavior is:
|
||||
- remove older managed-looking chunks when possible
|
||||
- preserve manual text outside the managed block
|
||||
- append the managed block when no block exists
|
||||
- keep the generated workflow block compact and front-loaded so it does not consume unnecessary model context in long legacy instruction files
|
||||
- keep the generated workflow block as a compact automatic-Sync trigger and boundary index so it does not consume unnecessary model context in long legacy instruction files
|
||||
- keep detailed report examples and long workflow procedure in explicit generated skill files instead of host instruction blocks
|
||||
|
||||
Repository-specific instructions should therefore live outside the managed block.
|
||||
@@ -111,12 +118,13 @@ Important current defaults:
|
||||
- default authority includes the canonical doc classes under `docs/`
|
||||
- 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`
|
||||
- default platforms are `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`
|
||||
- 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
|
||||
- generated workflow surfaces include a configured hierarchy summary and decision-truth guidance
|
||||
- managed instruction blocks include only compact hierarchy, decision-truth, automatic-Sync trigger, boundary reminders, and a pointer to explicit workflows; generated skills carry the detailed workflow bodies
|
||||
- `TRUTHMARK.md` is a compact branch-local truth contract and version marker, not a duplicate workflow procedure surface
|
||||
- scaffolded default standards include AI-native topology repair guidance so new repositories do not rely on human feature-folder discipline
|
||||
- Truth Sync is the only generated skill with implicit invocation enabled because it is the automatic finish-time workflow
|
||||
- `truthmark check` is optional validation for agent workflows, not a required workflow preflight
|
||||
@@ -144,12 +152,14 @@ Current init JSON reporting uses:
|
||||
- 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 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.
|
||||
- Managed instruction blocks are compact automatic-Sync indexes; generated skills and command files own explicit workflow procedure.
|
||||
- `TRUTHMARK.md` stays as a small branch-local contract so authority and branch-scope validation have a stable top-level anchor without duplicating `AGENTS.md`.
|
||||
|
||||
## Rationale
|
||||
|
||||
This split makes the hierarchy reviewable before generated workflow behavior lands in the repo. Keeping route ownership in Markdown preserves local editing ergonomics. Refusing silent migrations avoids accidental truth loss when a repository reshapes its canonical docs tree.
|
||||
|
||||
Keeping host-specific detail in generated skills and Gemini command files prevents the repository root from accumulating parallel instruction files that drift from the managed workflow contract.
|
||||
Keeping host-specific detail in generated skills and Gemini command files prevents the repository root from accumulating parallel instruction files that drift from the managed workflow contract. Keeping managed blocks and `TRUTHMARK.md` terse protects ordinary agent context while preserving the automatic Sync gate, workflow boundaries, and branch-local authority.
|
||||
|
||||
## Primary Code Files
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: feature
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-10
|
||||
source_of_truth:
|
||||
- ../../src/agents/instructions.ts
|
||||
- ../../src/agents/truth-structure.ts
|
||||
@@ -36,26 +36,27 @@ Supported platform values:
|
||||
- `codex`
|
||||
- `opencode`
|
||||
- `claude-code`
|
||||
- `cursor`
|
||||
- `github-copilot`
|
||||
- `gemini-cli`
|
||||
|
||||
The default platform list is `codex`, `opencode`, and `claude-code`. Teams can add more platforms later and rerun `truthmark init`.
|
||||
The default platform list includes all supported platforms. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`.
|
||||
|
||||
Workflow invocation examples:
|
||||
|
||||
- Truth Structure: `/skill truthmark-structure` in OpenCode-style hosts, `/truthmark-structure` or `$truthmark-structure` in Codex, and `/truthmark:structure` in Gemini CLI
|
||||
- Truth Sync: `/skill truthmark-sync` in OpenCode-style hosts, `/truthmark-sync` or `$truthmark-sync` in Codex, and `/truthmark:sync` in Gemini CLI
|
||||
- Truth Realize: `/skill truthmark-realize` in OpenCode-style hosts, `/truthmark-realize` or `$truthmark-realize` in Codex, and `/truthmark:realize` in Gemini CLI
|
||||
- Truth Check: `/skill truthmark-check` in OpenCode-style hosts, `/truthmark-check` or `$truthmark-check` in Codex, and `/truthmark:check` in Gemini CLI
|
||||
- Truth Structure: `/skill truthmark-structure` in OpenCode-style hosts, `/truthmark-structure` or `$truthmark-structure` in Codex, `/truthmark-structure` in Claude Code, `/truthmark-structure` in GitHub Copilot, and `/truthmark:structure` in Gemini CLI
|
||||
- Truth Sync: `/skill truthmark-sync` in OpenCode-style hosts, `/truthmark-sync` or `$truthmark-sync` in Codex, `/truthmark-sync` in Claude Code, `/truthmark-sync` in GitHub Copilot, and `/truthmark:sync` in Gemini CLI
|
||||
- Truth Realize: `/skill truthmark-realize` in OpenCode-style hosts, `/truthmark-realize` or `$truthmark-realize` in Codex, `/truthmark-realize` in Claude Code, `/truthmark-realize` in GitHub Copilot, and `/truthmark:realize` in Gemini CLI
|
||||
- Truth Check: `/skill truthmark-check` in OpenCode-style hosts, `/truthmark-check` or `$truthmark-check` in Codex, `/truthmark-check` in Claude Code, `/truthmark-check` in GitHub Copilot, and `/truthmark:check` in Gemini CLI
|
||||
- Claude Code installs project skills at `.claude/skills/truthmark-*/SKILL.md`, which surface as `/truthmark-structure`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check`
|
||||
- GitHub Copilot installs prompt files at `.github/prompts/truthmark-*.prompt.md`, which surface as `/truthmark-structure`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check` in supported Copilot IDEs
|
||||
- Gemini CLI installs project-scoped custom commands at `.gemini/commands/truthmark/*.toml`, which surface as `/truthmark:structure`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check`
|
||||
|
||||
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.
|
||||
The managed `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and equivalent platform instruction blocks are compact automatic-Sync trigger and boundary indexes. They intentionally omit non-automatic workflow procedures, report examples, and long 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, 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.
|
||||
Truthmark-owned workflow surfaces are generated under host-specific directories such as `.codex/skills/`, `.claude/skills/`, `.opencode/skills/`, and `.github/prompts/`. 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
|
||||
@@ -168,7 +169,7 @@ Truthmark currently provides installed workflow text, generated Codex and OpenCo
|
||||
## Product Decisions
|
||||
|
||||
- Installed skills and managed agent blocks are the workflow runtime; the CLI installs and validates those surfaces but does not orchestrate Truth Sync itself.
|
||||
- Generated instruction blocks must stay compact, while generated skills may carry detailed workflow bodies and report examples.
|
||||
- Generated instruction blocks must stay compact enough for ordinary agent context; non-automatic workflow procedure belongs in generated skills and command files.
|
||||
- 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`.
|
||||
@@ -178,7 +179,7 @@ Truthmark currently provides installed workflow text, generated Codex and OpenCo
|
||||
- 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.
|
||||
- Truthmark follows current host discovery paths for generated workflow files: Codex uses `.codex/skills/`, Claude Code uses `.claude/skills/`, GitHub Copilot uses `.github/prompts/`, OpenCode uses `.opencode/skills/`, and repo-root `skills/` is not a generated V1 target.
|
||||
|
||||
## Rationale
|
||||
|
||||
|
||||
Reference in New Issue
Block a user