Skip to content

feat: add project-governance skill - #22

Open
Century0327 wants to merge 2 commits into
trae-community:mainfrom
Century0327:add/project-governance-skill
Open

feat: add project-governance skill#22
Century0327 wants to merge 2 commits into
trae-community:mainfrom
Century0327:add/project-governance-skill

Conversation

@Century0327

@Century0327 Century0327 commented Aug 16, 2026

Copy link
Copy Markdown

Summary

Adds a project-governance skill: a lightweight, agent-readable governance layer for AI-assisted long-running projects. It turns implicit working conventions into explicit, versioned files that both humans and AI agents follow, so long-running agent work stays consistent, auditable, and reproducible across sessions — "not forget, not mess up, not repeat mistakes".

What's included

  • SKILL.md — when/how to scaffold and maintain a governance workspace (bilingual, 30-second overview, Memory & Governance Boundary, natural-language triggers)
  • README.md — package overview: Core / CLI / Skill-adapter structure, subcommands, limitations
  • templates/ — 11 templates: AGENTS.md (protocol: core rules, authority levels, first-run protocol, trust boundary), ARCHITECTURE.md, PROJECT.md, index.md (directory map with clickable links + notes), index_notes.json, LESSONS.md (error log), session_handoff.md, CHANGELOG.md, VERSIONS.md (stable version index), blacklist.json + whitelist.json (parameter registries)
  • scripts/governance.py — stdlib-only CLI with four subcommands:
    • init — scaffold the workspace from templates (idempotent, never overwrites without --force)
    • validate — schema-check blacklist/whitelist registries (--relaxed for migrating old registries)
    • index — rebuild index.md map from a filesystem scan (links + notes + truncation, customizable section names)
    • check — health gate: required files + valid registries + fresh index

Design highlights

  • Memory & Governance Boundary: platform memory is a context source, not an authoritative fact store. Authority priority: current project files / frozen versions > governance files > project memory > user memory > AI inference. Durable conventions from memory are settled into governance files after human confirmation.
  • File authority levels: AUTHORITATIVE / STABLE / EXPERIMENTAL / HISTORICAL / DEPRECATED / ARCHIVED — "file existence != file validity".
  • Execution discipline: index-first lookup, registry-driven parameters (whitelist score>0.85, never permanent_ban), lessons with corrections, session handoff, plan-before-execute, AI judgment never labeled human-approved.

Quality / testing

  • 76/76 test cases pass (43 basic + 17 boundary + 16 adversarial): non-UTF-8 encodings, directory-as-path, top-level non-object JSON, boolean-as-score, CRLF/BOM, deep nesting, special-char filenames, idempotency.
  • Test suite kept in the development repo, not shipped with the package (keeps the skill lean).
  • No secrets, no internal URLs, no customer data; fully desensitized.
  • Stdlib-only (argparse/json/pathlib), Python 3.8+.

PR checklist

  • skills/project-governance/SKILL.md exists with valid frontmatter (name, description <=1024 chars)
  • Includes usage guidance (README + SKILL.md instructions)
  • References files via relative links
  • MIT license compatible (no added license files needed)
  • Skills catalog updated in README.md and README.zh-CN.md
  • Verified locally: CLI lifecycle (init -> validate -> index -> check) + 76-case test suite

Project governance workspace for AI-assisted development: project protocol
(AGENTS.md), directory index, lessons log, session handoff, changelog,
version index, and whitelist/blacklist parameter registries.

Includes a stdlib-only CLI (scaffold/validate/index) and a 60-case
robustness/boundary test suite covering normal, edge, and adversarial
inputs. Adds the skill to the catalog in README.md and README.zh-CN.md.
- Slim package: drop tests/ and examples/ from the PR (kept in dev repo),
  add README.md documenting Core/CLI/Adapter structure + limitations
- SKILL.md: add Memory & Governance Boundary (authority priority), Input/Output
  and On Failure sections, natural-language trigger keywords, reposition to
  'not forget, not mess up, not repeat mistakes'
- governance.py: add check subcommand (health gate), index links + notes +
  truncation, --root-section/--changelog-section, --relaxed, markdown-aware
  section detection
- templates: AGENTS.md adds rule 9 (memory is context not authority) + boundary
  section + TOC; index.md new link+note format; add index_notes.json
- Update EN/ZH README skill catalogs (scaffold/validate/index/check CLI)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant