External/truthmark
1
0
Fork 0
mirror of https://github.com/merlinhu1/truthmark.git synced 2026-08-25 07:53:25 +02:00
Code Issues Packages Projects Releases Wiki Activity

v1.2.3 document skill, archictural revap (#2)

Browse Source
This commit is contained in:
MerlinH
2026-05-13 02:24:18 +10:00
committed by GitHub
parent 9a691dd84f
commit 6212f3d956
114 changed files with 3530 additions and 634 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai/agent-onboarding.md
+3 -2
View File
@@ -1,7 +1,7 @@
---
status: active
doc_type: agent-guide
last_reviewed: 2026-05-06
last_reviewed: 2026-05-13
source_of_truth:
- repo-rules.md
- ../README.md
@@ -44,9 +44,10 @@ Read:
Read:
1. [TRUTHMARK.md](../../TRUTHMARK.md)
1. [.truthmark/config.yml](../../.truthmark/config.yml)
2. [docs/features/installed-workflows.md](../features/installed-workflows.md)
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
4. [docs/ai/agent-skills-workflow-review.md](agent-skills-workflow-review.md)
### Documentation structure or policy changes
docs/ai/agent-skills-workflow-review.md
+91
View File
@@ -0,0 +1,91 @@
---
status: active
doc_type: agent-guide
last_reviewed: 2026-05-13
source_of_truth:
- repo-rules.md
- ../features/installed-workflows.md
- ../../.codex/skills/truthmark-sync/SKILL.md
- ../../.codex/skills/truthmark-structure/SKILL.md
- ../../.codex/skills/truthmark-document/SKILL.md
- ../../.codex/skills/truthmark-realize/SKILL.md
- ../../.codex/skills/truthmark-check/SKILL.md
- https://developers.openai.com/codex/skills
- https://developers.openai.com/blog/eval-skills
- https://developers.openai.com/blog/skills-shell-tips
- https://developers.openai.com/blog/skills-agents-sdk
- https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- https://docs.anthropic.com/en/docs/claude-code/slash-commands
---
# Agent Skills And Workflow Review
This note summarizes the external skill-authoring guidance reviewed on 2026-05-13 and applies it to Truthmark's installed project workflows. It is a reference for future workflow-surface changes, not a replacement for [installed-workflows.md](../features/installed-workflows.md).
## External Standard
Agent skills should be small, concrete, and triggerable from metadata alone. OpenAI and Anthropic both treat `name` and `description` as the first progressive-disclosure layer: the agent decides whether to load the full `SKILL.md` from that metadata. The description therefore needs concrete use cases, non-use cases, expected outputs, and success criteria.
Keep `SKILL.md` focused on the core procedure. Move rare, variant-specific, or long reference material into explicitly linked `references/` files. Use `scripts/` only for deterministic repeated mechanics; leave interpretation, comparison, judgment, and reporting to the model.
Reliable skills need validation, not only syntax checks. Deterministic tests can prove rendered metadata, required routing cues, report shapes, and write-boundary text. They cannot prove that every future AI agent will select the right skill in every realistic conversation.
Security posture matters because skills can contain instructions, scripts, assets, and external dependencies. Treat installed skills as executable agent runtime: inspect the bundled files, scripts, dependency behavior, and any network instructions before trusting them.
## Installed Surface
Truthmark currently installs five workflows across host-specific surfaces:
| Workflow | Main purpose | Codex implicit policy |
| --- | --- | --- |
| `truthmark-sync` | Finish-time code-to-truth synchronization after functional code changes | `allow_implicit_invocation: true` |
| `truthmark-structure` | Design or repair truth routing topology | `allow_implicit_invocation: false` |
| `truthmark-document` | Document existing implemented behavior without code changes | `allow_implicit_invocation: false` |
| `truthmark-realize` | Realize truth docs into functional code | `allow_implicit_invocation: false` |
| `truthmark-check` | Audit repository truth health | `allow_implicit_invocation: false` |
Generated runtime surfaces include `.codex/skills/`, `.claude/skills/`, `.opencode/skills/`, `.github/prompts/`, `.gemini/commands/truthmark/`, and compact managed instruction blocks in files such as `AGENTS.md`.
## What Is Working
- The workflow split is coherent: Structure owns topology, Document owns implemented behavior without code changes, Sync owns code-first finish-time alignment, Realize owns doc-first code changes, and Check owns audit.
- Write boundaries are unusually clear. The skills repeatedly state which docs, routing files, or functional code may be changed.
- The runtime is agent-native. Skills tell agents to inspect the checkout directly and treat the CLI as optional validation rather than a required orchestration bridge.
- The managed instruction block is compact while the detailed procedures live in explicit workflow surfaces, which preserves ordinary task context.
- Codex metadata correctly makes only Sync implicitly invocable. Manual workflows remain explicit in Codex, which reduces accidental Structure, Document, Realize, or Check runs.
- Generated-surface tests cover parseable frontmatter, required phrases, report headings, host paths, version markers, and stale-surface diagnostics.
## Critical Findings
1. Medium: frontmatter descriptions need explicit negative routing cases.
The body text has good boundaries, but the body loads only after the skill triggers. Descriptions should include concise "do not use when" clauses for nearby workflows. This matters most for Structure versus Document, Document versus Sync, and Check versus ordinary validation.
2. Low: repeated hierarchy and decision-truth text increases drift risk.
The duplication is defensible because generated host surfaces should remain standalone after install. Still, shared generator constants and tests should continue to own this text. If the body grows substantially, consider a generated `references/truthmark-common.md` only when each supported host reliably exposes skill references.
3. Low: `truthmark-check` can read like a replacement for normal verification.
The skill body says `truthmark check` is optional and direct inspection is canonical. The description could still clarify that Truth Check is for repository-truth audits, not a substitute for lint, tests, typecheck, code review, or the finish-time Sync gate.
## Resolved Notes
- Resolved 2026-05-13: `truthmark-document` metadata now names Truth Sync, Truth Check, and Truth Structure as the workflows that can hand off missing implemented-behavior documentation.
- Resolved 2026-05-13: `truthmark-sync` frontmatter and Codex metadata now include skip cases for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, and no functional code changes.
## Deterministic Coverage Matrix
| Workflow | Positive trigger examples | Negative trigger examples | Key success checks |
| --- | --- | --- | --- |
| Sync | "I changed session code; finish and sync truth" | docs-only edit, formatting-only edit, no functional code diff | reads changed code and routing, updates only truth docs or routing, reports skipped or blocked correctly |
| Structure | "split broad repository routing into auth and billing" | "document current auth behavior" | repairs route topology before docs, creates bounded starter docs, preserves authored content |
| Document | "document existing order submission behavior" | "implement the behavior in this truth doc" | reads code and tests, writes docs/routing only, does not edit functional code |
| Realize | "realize docs/features/auth/session-timeout.md into code" | "sync docs after my code change" | reads truth docs first, edits functional code only, runs relevant tests |
| Check | "audit truth health before review" | "run lint and tests" | reports issues and suggested fixes, optionally runs `truthmark check`, does not silently rewrite unrelated files |
## Next Improvements
- Add deterministic description-quality tests that require positive and negative routing cues in every generated `SKILL.md` description.
- Treat prompt-style agent evals, if ever added, as smoke checks and examples rather than proof of universal routing correctness.
- Tighten `truthmark-check` descriptions before adding more workflows.
- Keep generated skill bodies below the point where common guidance crowds out workflow-specific procedure.
- Re-audit security posture before any Truthmark skill gains scripts, assets, or network-capable dependencies.
docs/ai/repo-rules.md
+14 -17
View File
@@ -1,23 +1,22 @@
---
status: active
doc_type: agent-rules
last_reviewed: 2026-05-10
last_reviewed: 2026-05-13
source_of_truth:
- ../../AGENTS.md
- ../README.md
- ../../TRUTHMARK.md
---
# Repository Rules
Repository-wide agent authority, routing, and completion rules. Prefer the smallest sufficient read; detailed behavior lives in [docs/](../README.md).
Repository-wide agent authority, routing, and completion rules. Read the smallest sufficient set; detailed behavior lives in [docs/](../README.md).
## Authority
Conflict order:
1. this file
2. [TRUTHMARK.md](../../TRUTHMARK.md)
2. [.truthmark/config.yml](../../.truthmark/config.yml)
3. [docs/truthmark/areas.md](../truthmark/areas.md) and `docs/truthmark/areas/**/*.md`
4. `docs/standards/**/*.md`
5. `docs/architecture/**/*.md`
@@ -25,36 +24,34 @@ Conflict order:
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.
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.
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 required.
## Product Boundary
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.
Truthmark has three CLI commands: `config`, `init`, and `check`. Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check are installed workflow surfaces, not CLI commands.
Agents inspect the active checkout directly. There is no daemon, database, remote service, or V1 MCP server.
## Rules
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.
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.
7. Behavior, contract, workflow, and completion-rule changes update the nearest canonical doc. Major product/onboarding/install/command/positioning/workflow changes also update the root README. A material root README change blocks completion until the localized root READMEs change in the same working change.
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.
9. Follow [testing-and-verification.md](../standards/testing-and-verification.md) and [pre-completion-checklist.md](../standards/pre-completion-checklist.md). Define success criteria. Continue 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.
11. Tests prove supported behavior and current contracts. Do not prove a removal by asserting that a deleted string or file is absent unless that absence is the protected boundary.
## Routing
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).
Fast task routing lives in [agent-onboarding.md](agent-onboarding.md). Read only the docs that govern the slice you are changing.
- 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).
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.
If blocked, re-read the relevant canonical docs and owning implementation, then surface the blocker instead of guessing. If one file diverges from an established pattern, require justification before copying it.
## Maintenance
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`.
Update this file only for repository-wide agent rules. Keep it compact and policy-focused. Put procedures in standards or guides, feature behavior in `docs/features`, and update `last_reviewed`.