You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
WIP: centralize agent instructions via nested includes
CLAUDE.md now includes docs/development/index.md. AGENTS.md and
copilot-instructions.md include CLAUDE.md, getting everything
transitively. CLAUDE.md exceeds the 300-line limit — needs a
more concise structure before merging.
https://claude.ai/code/session_01J3g8NnEwGYyJWXD1bqtTii
<!-- Included content comes from docs/development/index.md.
4
-
Edit that file first, then run
3
+
<!-- Included content comes from CLAUDE.md (which
4
+
itself includes docs/development/index.md).
5
+
Edit those files first, then run
5
6
`mdsmith fix .` to propagate. -->
6
7
7
8
Instructions for AI coding agents (Codex, Copilot,
8
-
Claude). See [CLAUDE.md](CLAUDE.md) for full project
9
-
conventions.
9
+
Claude).
10
+
11
+
<?include
12
+
file: CLAUDE.md
13
+
strip-frontmatter: "true"
14
+
?>
15
+
# CLAUDE.md
16
+
17
+
## Project
18
+
19
+
mdsmith — a Markdown linter written in Go.
20
+
21
+
## Docs
22
+
23
+
-[Plan template; see PLAN.md for status, plans live in plan/](plan/proto.md)
24
+
25
+
<?catalog
26
+
glob:
27
+
- "docs/**/*.md"
28
+
- "!docs/research/**"
29
+
- "!docs/security/**"
30
+
sort: path
31
+
header: ""
32
+
row: "- [{summary}]({filename})"
33
+
?>
34
+
-[How generated sections work — markers, directives, and fix behavior.](docs/background/archetypes/generated-section/README.md)
35
+
-[Shared patterns (archetypes) reused across multiple linting rules.](docs/background/archetypes/README.md)
36
+
-[Comparison of mdsmith with other Markdown linters and formatters.](docs/background/markdown-linters.md)
37
+
-[Build commands, project layout, code style, test fixtures, coverage gate, and merge conflicts.](docs/development/index.md)
38
+
-[PR fixup workflow for rebase, CI monitoring, review comment resolution, and gh CLI setup.](docs/development/pr-fixup-workflow.md)
39
+
-[How to use schemas, require, and allow-empty-section to validate headings, front matter, and filenames.](docs/guides/directives/enforcing-structure.md)
40
+
-[How to use catalog and include directives to generate and embed content in Markdown files.](docs/guides/directives/generating-content.md)
41
+
-[Key differences between Hugo templates and mdsmith directives for users familiar with Hugo.](docs/guides/directives/hugo-migration.md)
42
+
-[User guides for mdsmith directives, structure enforcement, and migration.](docs/guides/index.md)
43
+
-[Trade-offs and threshold guidance for readability, structure, length, and token budgets.](docs/guides/metrics-tradeoffs.md)
44
+
-[CLI commands, flags, exit codes, and output format.](docs/reference/cli.md)
45
+
<?/catalog?>
46
+
47
+
## Development Workflow
48
+
49
+
- Any change follows Red / Green TDD: write a failing
50
+
test (red), make it pass (green), commit
51
+
- Keep commits small and focused on one change
52
+
- Run `mdsmith check .` before committing to ensure all
53
+
markdown files pass linting
54
+
- Never modify `.mdsmith.yml` (linter configuration)
55
+
without explicit user consent — this includes rule
56
+
settings, overrides, ignore patterns, and file-length
57
+
limits
58
+
59
+
## PR Workflow
60
+
61
+
Use `gh` for all GitHub PR operations:
62
+
63
+
```bash
64
+
# View PR comments
65
+
gh pr view <number> --comments
66
+
67
+
# List review comments on a PR
68
+
gh api repos/"$(gh repo view --json nameWithOwner \
69
+
-q '.nameWithOwner')"/pulls/<number>/comments \
70
+
--paginate
71
+
72
+
# Resolve a review thread after addressing it
73
+
gh api graphql -f query='mutation {
74
+
resolveReviewThread(input: {threadId: "ID"}) {
75
+
thread { id isResolved }
76
+
}
77
+
}'
78
+
79
+
# Push updates after addressing comments
80
+
git push origin <branch>
81
+
```
82
+
83
+
These commands are auto-approved in
84
+
[`.claude/settings.json`](.claude/settings.json).
85
+
86
+
## Plan Maintenance
87
+
88
+
When implementing work tracked by a plan file in
89
+
`plan/`:
90
+
91
+
- Update the plan file **as part of the
92
+
implementation**, not as a separate follow-up
93
+
- Check off each task (`- [x]`) as it is completed
94
+
- Check off each acceptance criterion when verified
95
+
- When all acceptance criteria are met, change the
96
+
front-matter `status` from `🔲` or `🔳` to `✅`
97
+
- When work begins on a not-started plan, change
98
+
`status` from `🔲` to `🔳`
99
+
- If the implementation deviates from the plan
100
+
(e.g. a parameter name changes), update the plan
101
+
text to match what was actually built
102
+
- Run `mdsmith fix PLAN.md` after changing a plan's
103
+
front matter so the catalog table stays current
104
+
105
+
## Terminal Demo (`demo.tape`)
106
+
107
+
The repo includes a VHS tape file (`demo.tape`) that
108
+
records a terminal demo GIF. When editing this file:
109
+
110
+
- VHS uses backtick-delimited strings to embed quotes:
111
+
`` Type `cmd 'status: "✅"'` `` — do NOT use `\"`
112
+
inside double-quoted Type strings (VHS crashes)
113
+
- The tape runs `set +e` (hidden) at the start so
114
+
non-zero exits don't abort the recording — no need
115
+
to append `; true` to commands
116
+
-`demo/sample.md` is in the `.mdsmith.yml` ignore
117
+
list; the hidden setup copies it to a temp dir
118
+
for check/fix steps
119
+
- Keep Sleep durations short (1–2 s) so VHS renders
120
+
quickly in CI
121
+
- Only use fixable lint rules in `demo/sample.md`
122
+
(e.g. trailing spaces, long lines, bare URLs) so
123
+
the "fix then clean check" flow works
124
+
125
+
## Writing Guidelines
126
+
127
+
When writing descriptions, state the concrete constraint:
128
+
what specific data must satisfy what condition. Name the
0 commit comments