Skip to content

Commit 058aeb9

Browse files
llblabllblab
committed
0.3.0: _
1 parent d5db073 commit 058aeb9

65 files changed

Lines changed: 18092 additions & 6498 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/evolve-context/AGENTS.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# AGENTS.md (evolve-context)
2+
3+
## Knowledge & Conventions
4+
5+
### Meta-Protocol Principles
6+
7+
- 'Self-Reference': This skill must validate its own documentation using its own scripts.
8+
- 'Root State Separation': Durable protocol belongs in `AGENTS.md`, open work belongs in `BACKLOG.md`, and completed delivery belongs in `CHANGELOG.md`.
9+
- 'Hybrid Context Coverage': The protocol serves ABC + README entrypoints + `/docs` as one coordinated context graph.
10+
- 'Cross-Platform': Scripts must support both Linux and MacOS.
11+
- 'Self-Enhancement': Protocols anticipate and facilitate their own evolution.
12+
- 'Workflow Stratification': Preparation → execution → reflection → documentation.
13+
14+
### Operating Principles
15+
16+
- Use `validate-context` for all documentation audits.
17+
- Use `scripts/_self-test` to verify skill integrity after changes.
18+
- Prefer the ABC root control plane: `README.md` + `AGENTS.md` + `BACKLOG.md` + `CHANGELOG.md`, with subtree `README.md` files as human entrypoints and `docs/README.md` + `/docs` as the knowledge plane.
19+
- SKILL.md stays compact; `docs/protocols.md` contains only what SKILL.md does not.
20+
- `BACKLOG.md` keeps only remaining open, gated, or blocked work; close or narrow items in the same pass that changed reality.
21+
- `CHANGELOG.md` tracks completed delivery history; `AGENTS.md` should not accumulate per-iteration delivery logs when `CHANGELOG.md` exists.
22+
- Keep root `README.md` connected to `AGENTS.md`, `BACKLOG.md`, `CHANGELOG.md`, and `docs/README.md`.
23+
- Keep subtree `README.md` files reachable from parent/root/docs navigation once they become real human entrypoints.
24+
25+
### Discovered Constraints
26+
27+
- 'Farmville Trap': If the protocol generates more documentation updates than actually prevented mistakes, it has become a Tool Shaped Object. Measure value by errors avoided, not files touched. | Trigger: Post-task protocol fires but produces no actionable insight | Action: Skip the update. Silence is a valid output.
28+
- 'Progressive Disclosure over Always-On': ALWAYS_ON mode costs agent attention on every turn even when irrelevant. Prefer POST_TASK as default. | Trigger: Agent tracking overhead exceeds insight value | Action: Default to POST_TASK; use ALWAYS_ON only when explicitly requested.
29+
- 'A2 applies to templates': Context templates must start minimal — imposing principles and ceremony on a new project violates Axiom A2. Template is a skeleton that grows with the project, not a manifesto.
30+
- 'Self-contradiction kills trust': Absolute rules must survive contact with every other rule in the system. "Mandatory" + "skip if empty" is a contradiction — use conditional language.
31+
- 'Durable/open/completed state must not collapse': If the same reality is tracked simultaneously in `AGENTS.md`, `BACKLOG.md`, and `CHANGELOG.md`, the protocol loses truthfulness. Route each fact to exactly one root file.
32+
- 'README tree is part of context, not decoration': Root and subtree `README.md` files are human-facing entrypoints and must be updated when setup, usage, topology, or same-domain insight truth changes.
33+
- 'Per-iteration delivery history belongs in CHANGELOG': Once a project keeps `CHANGELOG.md`, `AGENTS.md` should store reusable constraints, not rolling delivery bullets.
34+
- 'Minimal starter != permanent ceiling': Minimal AGENTS templates are acceptable for early projects, but mature repositories should grow a layered hierarchy when constraints justify it.
35+
- 'LLM YAML tracking is fictional': LLMs reason in natural language, not structured YAML. Tracking schemas in prompts create illusion of process. Post-task evaluation does the actual work.
36+
- 'Ceremonial formalization': If pseudocode describes what an experienced developer would do by default, the formalization adds no value. Formalize only non-obvious protocols.
37+
- `stat` command differs between Linux (`-c %Y`) and MacOS (`-f %m`).
38+
- `grep -P` is unavailable on macOS BSD grep — use `grep -oE` + `sed` instead.
39+
- `heading_to_anchor` must preserve underscores `_` to match GitHub's anchor generation.
40+
- `[[ cond ]] && action` in a function with `set -e` exits on false — use `if/fi` or `|| true`.
41+
- `\$[^$]+\$` regex false-positives on shell variables — check for LaTeX commands specifically.
42+
- "Core structure" check now accepts both `## 1.` project sections and skill-style key sections.
43+
- Scripts use no file extension — shebangs (`#!/usr/bin/env bash`) define the interpreter.
44+
- `realpath --relative-to` is GNU-specific — prefer path-prefix stripping for docs-relative paths.
45+
- UTF-8 locales differ by platform (`en_US.UTF-8`, `C.UTF-8`, `C.utf8`) — include safe `C` fallback.

‎.agents/skills/evolve-context/BACKLOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Evolve Context Backlog
2+
3+
> Canonical open backlog for the skill.
4+
> Pair with `AGENTS.md` for durable protocol and `CHANGELOG.md` for completed delivery history.
5+
6+
## Open Backlog
7+
8+
- [ ] `Add deeper validator checks for root-state drift:` detect more cases where the same completed slice appears both open in `BACKLOG.md` and delivered in `CHANGELOG.md` instead of stopping at file-presence and structural checks.
9+
- [ ] `Add an ABC-style fixture project for validator regression tests:` move more self-test coverage out of inline heredocs and into a reusable fixture that models the preferred root standard directly.
10+
- [ ] `Document coexistence with stricter project-local overlays:` explain how `evolve-context` should hand off to repository-specific gatekeepers and alignment skills without duplicating their rules.

‎.agents/skills/evolve-context/CHANGELOG.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Changelog
2+
3+
## 1.3.0
4+
5+
- Replaced placeholder meta-protocol headings in the `AGENTS.md` templates with concrete principle sets so new and restructured projects start with an actual governing philosophy rather than empty scaffolding.
6+
- Clarified in the protocol docs that meta-protocol sections should be instantiated, not left as symbolic placeholders.
7+
- Clarified that `evolve-context` should not only scaffold new projects but also restructure existing context files toward the chosen template when the current shape is too flat or mixed-level.
8+
- Added explicit meta-protocol principles to the lean `AGENTS.md` starter so both template tracks explain how context itself should evolve.
9+
- Split the `AGENTS.md` starter guidance into two explicit tracks: a lean starter for small projects and a layered mature-project starter for repositories that need a protocol hierarchy closer to evolved systems like `tmctol`.
10+
- Clarified in the protocol docs that template choice should follow real project maturity instead of forcing either minimalism or heavy structure by default.
11+
- Expanded the skill from an ABC-only correction pass into a hybrid context reconciler that explicitly serves `ABC + README tree + /docs`.
12+
- Elevated root and subtree `README.md` files to first-class managed targets in the protocol, templates, and validation design.
13+
- Extended `validate-context` and `_self-test` to treat README reachability as part of context health instead of auditing only root files and docs.
14+
- Re-expanded the AGENTS starter guidance from minimal-only toward a layered mature-project structure modeled on evolved repositories, and made same-domain README insight refresh an explicit completion expectation.
15+
- Reframed the skill around the organic ABC root standard: `AGENTS.md` now owns durable protocol, `BACKLOG.md` owns open work, and `CHANGELOG.md` owns completed delivery history.
16+
- Removed the old expectation that `AGENTS.md` should carry rolling Change History entries and updated the docs/templates/validator to prefer root-state separation instead.
17+
- Added a first-class `BACKLOG.md` to the skill itself, updated README connectivity to expose the full root control plane, and expanded self-tests around the ABC split.
18+
19+
## 1.0.0
20+
21+
- Structural cleanup: protocols.md 261→90 lines, removed Session Initialization ceremony, During-Task YAML tracking, Post-Task Protocol Full (now inline in SKILL.md)
22+
- Context Template made minimal and A2-aligned: removed 9 Meta-Protocol Principles, Pre/Post-Task protocols from template
23+
- Full post-task steps inlined in SKILL.md (no external link dependency)
24+
- Index file naming: `AGENTS.md` primary, alternatives listed as fallback
25+
- Added discovered constraints: A2-templates, self-contradiction, LLM YAML fiction, ceremonial formalization
26+
- protocols.md now contains only delta: adaptation rules, lifecycle management, validation checklist
27+
28+
## 0.4.0
29+
30+
- Added self-test script (32 assertions)
31+
- Fixed "Core structure sections missing" false positive for skill AGENTS.md
32+
- Core structure check now accepts both `## 1.` and skill-style key sections
33+
34+
## 0.3.0
35+
36+
- Major refactor: SKILL.md compressed from 573 to 161 lines
37+
- Detailed protocols extracted to `docs/protocols.md`
38+
- Introduced light/full post-task protocol tiers (3 vs 8 steps)
39+
- Added `--json` output mode to `validate-context`
40+
- Fixed `grep -P` → `grep -oE` for macOS compatibility
41+
- Fixed `heading_to_anchor` to preserve underscores (GitHub compat)
42+
- Fixed LaTeX detection false positives on shell variables like `$HOME`
43+
- Added ERR trap for runtime crash diagnostics
44+
- Added `docs/protocols.md` — full protocol specifications
45+
46+
## 0.2.0
47+
48+
- Three-layer architecture (README → Index → Docs)
49+
- `validate-context` with 10+ checks
50+
- Bloat analysis with heuristic signals
51+
- Entry templates extracted to `docs/templates.md`
52+
- Anchor validation for GitHub-style headings
53+
54+
## 0.1.0
55+
56+
- Initial release of the Context Evolution Protocol skill

‎.agents/skills/evolve-context/README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Evolve Context Skill
2+
3+
Self-evolving context protocol for agent projects.
4+
5+
## Platform Support
6+
7+
- 'Linux'
8+
- 'MacOS'
9+
10+
## Features
11+
12+
- 'ABC Root Control Plane': `AGENTS.md` for durable protocol, `BACKLOG.md` for open work, `CHANGELOG.md` for completed delivery.
13+
- 'README Entrypoint Graph': Root and subtree `README.md` files are treated as human navigation surfaces that must stay current.
14+
- 'Adaptive AGENTS Templates': The skill now provides both lean and layered mature-project `AGENTS.md` starters, both with concrete meta-protocol principles instead of placeholder headings.
15+
- 'Restructuring Existing Context': Templates are also restructuring targets for inherited or overgrown context files, not only greenfield starters.
16+
- 'Documentation Routing': `docs/README.md` and `/docs` stay the broad subsystem knowledge plane.
17+
- 'Automated Validation': `validate-context` audits ABC cohesion, README reachability, links, and docs coverage.
18+
19+
## Quick Start
20+
21+
```bash
22+
"${SKILL_DIR}/scripts/_bootstrap"
23+
```
24+
25+
## Quick Links
26+
27+
- [Skill Definition](SKILL.md)
28+
- [Project Index](AGENTS.md)
29+
- [Open Backlog](BACKLOG.md)
30+
- [Delivery History](CHANGELOG.md)
31+
- [Documentation Index](docs/README.md)

0 commit comments

Comments
 (0)