mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
63 lines
4.5 KiB
Markdown
63 lines
4.5 KiB
Markdown
Follow `docs/ai/repo-rules.md`.
|
|
|
|
Use that file as the primary repository instruction source for Codex.
|
|
|
|
Codex-specific:
|
|
- Read `docs/README.md` for the canonical docs map.
|
|
- Use `docs/ai/agent-onboarding.md` for quick task routing.
|
|
|
|
<!-- truthmark:start -->
|
|
## Truthmark Workflow
|
|
|
|
Generated by Truthmark 1.2.1. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
|
|
|
Truthmark hierarchy:
|
|
- Config: .truthmark/config.yml
|
|
- Root route index: docs/truthmark/areas.md
|
|
- Area route files: docs/truthmark/areas/**/*.md
|
|
- Feature docs: docs/features/**/*.md
|
|
|
|
Decision truth lives in the canonical doc it governs.
|
|
Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.
|
|
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
|
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
|
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
|
|
|
### Truth Structure
|
|
Use when area routing is missing, stale, broad, or explicitly requested.
|
|
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Gemini CLI /truthmark:structure.
|
|
Inspect repository layout, docs/truthmark/areas.md, relevant child route files, canonical docs, and relevant code directly.
|
|
Create or repair routing and starter canonical truth docs only when useful. Use only canonical current-truth destinations for starter truth docs.
|
|
Own topology pressure: split broad/catch-all routing by inferred product or behavior ownership.
|
|
If the skill is unavailable, perform the same direct checkout workflow from committed config, route files, docs, and implementation.
|
|
|
|
### Truth Sync
|
|
Automatic finish-time trigger: use the truthmark-sync skill before finishing if changed functional code exists; inspect staged, unstaged, and untracked functional code files.
|
|
Explicit invocation runs immediately: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Gemini CLI /truthmark:sync.
|
|
Later functional-code changes reopen the finish-time requirement, and an earlier explicit run only satisfies the finish gate if no later functional-code changes occur.
|
|
Memory anchor: code changed -> relevant tests -> Truth Sync -> report.
|
|
Delegate to a subagent only when the host supports subagent dispatch; the acting agent and environment own that choice.
|
|
Inspect the current checkout directly. Do not invoke packet helpers or rely on cache files.
|
|
Run relevant tests before finishing when functional code changes occurred.
|
|
Truthmark is agent-native: installed skills and this managed block are the workflow runtime. Inspect the checkout directly; truthmark CLI commands are optional validation tools after installation.
|
|
Code first: code leads; truth docs follow; Truth Sync never rewrites code for alignment.
|
|
May write truth docs and docs/truthmark/areas.md only; must not rewrite functional code.
|
|
Read docs/truthmark/areas.md and only relevant child route files under docs/truthmark/areas/ when routing resolution requires them.
|
|
If routing is broad, overloaded, or catch-all, run or recommend Truth Structure before syncing; do not create another generic feature doc.
|
|
If mapped truth is missing, extend mapped truth docs first, create an area-local truth doc second, and create a new area only as a last resort.
|
|
Skip only for: documentation-only change; formatting-only change; clearly behavior-preserving rename with no truth impact; no Truthmark config exists yet; no functional code changes.
|
|
|
|
### Manual Truth Realize
|
|
Only run when the user explicitly asks to realize truth docs into code. This is a manual installed instruction or skill, not a dedicated CLI command.
|
|
Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Gemini CLI /truthmark:realize.
|
|
Doc first: read truth docs, routing, and relevant code; write functional code only; do not edit truth docs or truth routing.
|
|
Report truth docs used, code updated, and verification.
|
|
|
|
### Truth Check
|
|
Use when the user asks to audit repository truth health.
|
|
Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Gemini CLI /truthmark:check.
|
|
Inspect truth docs, routing, implementation, and docs/truthmark/areas.md directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.
|
|
|
|
Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries.
|
|
<!-- truthmark:end -->
|