# Agent Instructions (playbook)

> About the special nature of the playbook repo:
>
> - In the playbook repo: ruleset templates live in `rulesets/`
> - In target projects: after sync from playbook, rulesets live in `.agents/`
> - AI agents read `.agents/` in the target project root (generated by sync_standards.sh)
>
> This document applies to target projects. The playbook repo itself has no
> source code and does not need AI agent rules.

Use the rules under `.agents/` as the source of truth:

- Entry: `.agents/index.md`
- Language rules: `.agents/tsl/index.md`, `.agents/cpp/index.md`,
  `.agents/python/index.md`, `.agents/markdown/index.md`

---

## Three-layer architecture (layered knowledge base)

This repo organizes agent rules and knowledge into three layers:

### Layer 1: `.agents/` (minimal hard rules, <= 50 lines per language)

- Load: automatic, always in context
- Content: hard constraints and safety red lines
- Role: quick decisions on what can or cannot be done
- Size control: TSL 47 lines | Python 48 lines | C++ 50 lines | Markdown 23 lines

### Layer 2: `codex/skills/` (on-demand, 100-1000 lines per skill)

- Load: triggered by `$<skill-name>` or inferred by the agent
- Content: how-to guidance, best practices, workflows
- Role: detailed guidance on how to do the task

Key skills:

- `$tsl-guide` - progressive TSL syntax training (basic/advanced/functions/best practices)
- `$testing-workflow` - cross-language testing strategy
- `$code-review-workflow` - code review workflow
- `$commit-message` - commit message convention
- `$create-plan` - create a concise plan
- `$style-cleanup` - formatting/style cleanup
- `$bulk-refactor-workflow` - safe bulk refactor workflow

### Layer 3: `docs/` (authoritative static docs)

- Load: on-demand for specific sections
- Content: full language manuals, code style, toolchain config
- Role: the final authority
- Conflict handling: when rules conflict, follow `docs/`

Note: the function library is split under `docs/tsl/syntax_book/function/`.
Do not load the whole directory. Load only the needed fragments.

---

## Usage scenarios

### Scenario 1: write a simple TSL function

```text
1. Auto read .agents/tsl/index.md (47 lines)
2. Trigger $tsl-guide, load SKILL.md (192 lines)
3. Generate code

Token cost: ~6,000 tokens
```

### Scenario 2: write a TSL class

```text
1. Auto read .agents/tsl/index.md (47 lines)
2. Trigger $tsl-guide, load SKILL.md + references/advanced.md
3. Generate code

Token cost: ~10,000 tokens
```

### Scenario 3: find a TSL function library entry

```text
1. Auto read .agents/tsl/index.md (47 lines)
2. Trigger $tsl-guide, load references/functions_index.md
3. Use rg to locate the function fragment
4. Return the answer

Token cost: ~8,000 tokens
```

---

## Performance metrics

| Metric              | Before     | Now       | Improvement |
| ------------------- | ---------- | --------- | ----------- |
| .agents size        | ~500 lines | 168 lines | -66%        |
| Persistent tokens   | ~12,500    | ~4,200    | -66%        |
| Avg scenario tokens | ~12,500    | ~10,500   | -16%        |

---

## Maintenance principles

### .agents/ modification rules

Do:

- Add new security vulnerability types
- Update core conventions (file names, format rules)
- Add non-negotiable hard constraints

Do not:

- Add recommended best practices (put them in a skill)
- Add detailed syntax explanations (put them in a skill or docs)
- Exceed the 50-line limit (split into skills)

### Skills creation rules

Do:

- Add new workflows (e.g., code-review)
- Teach a new language from scratch (e.g., tsl-guide)
- Add cross-language common knowledge (e.g., testing-workflow)

---

## FAQ

Q: Why is .agents/ so small?
A: Because it is loaded every conversation. Keeping it under 50 lines saves
about 71% of persistent token usage.

Q: Why does TSL need a dedicated tsl-guide skill?
A: TSL is not pre-trained. The agent needs from-scratch teaching.

Q: What if my project has custom conventions?
A: Fork playbook into the project (git subtree) and modify the project's
`.agents/`.

---

## Related docs

- Skills usage guide: `SKILLS.md`
- Development standards: `docs/index.md`
- Project README: `README.md`