diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index fb65c35..474c717 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -35,7 +35,7 @@ The universal baseline is in `AGENTS.md`. This file restates the parts that matt ## Build, test, and dependencies -- This repo currently has no build step, no package manager, and no test runner. +- This repo has no build step and no package manager. Doc-quality checks run via `./scripts/check.sh` locally and the `doc-quality` workflow in CI. - Do not suggest installing or updating packages. - If code samples are added later, place them under `examples/` and include a runnable command in the same file. diff --git a/AGENTS.md b/AGENTS.md index f32399c..84a71ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,7 +52,7 @@ Claude Code does not read this file natively; `CLAUDE.md` cross-references it vi Before declaring a change done: -- [ ] Markdown lints clean if the project has a linter configured (none yet — add one if it lands). +- [ ] `./scripts/check.sh` passes (file-length cap, Boundaries sections, markdownlint, offline link check, typos). CI runs the same tiers in `.github/workflows/doc-quality.yml`. In a repo without the runner, lint markdown with whatever linter the project configures. - [ ] All cross-references resolve. `grep -RIn '\](\./\|](docs/\|](\.github/' .` and confirm targets exist. - [ ] No secrets in the diff. `git diff --cached | grep -iE 'api[_-]?key|secret|token|password'` returns nothing. - [ ] Each new or edited rule is imperative and verifiable. @@ -61,7 +61,7 @@ Before declaring a change done: ## Dev environment tips -- This repo currently ships only markdown. There is no build step, no package manager, and no test runner. +- This repo ships markdown plus doc-quality tooling. There is no build step and no package manager; validation runs through `./scripts/check.sh` locally and the `doc-quality` workflow in CI. - If code samples are added later, place them under `examples/` and include a runnable command in the same file. - Do not add dependencies unless a sample explicitly requires them. @@ -128,6 +128,7 @@ When the user provides repos, guides, articles, or PDFs: - `BOOTSTRAP.md` — drop-in install commands and replace-before-use checklist for seeding a new repo. - `.github/workflows/*.yml` — repo-specific CI; not part of the bootstrap-template surface. - `.markdownlint.json` — tier-2 lint config; consumed by `markdownlint-cli2` locally and in CI. +- `lychee.toml` — link-check config; excludes intentionally unreachable placeholder URLs (e.g., `` in `BOOTSTRAP.md`). - `scripts/check.sh` — local runner that mirrors the CI tiers; auto-skips uninstalled tools. - `docs/ai-agent-coding-strategy.md` — human-facing strategy, not enforced as rules. - `docs/research-log.md` — observations vs. promoted rules. diff --git a/CLAUDE.md b/CLAUDE.md index bd9c80b..13cf2e7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ The cross-agent baseline lives in [`AGENTS.md`](./AGENTS.md). Read it first; the 1. **Bootstrap source** for new projects — `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` are designed to drop into a fresh repo. See [`BOOTSTRAP.md`](./BOOTSTRAP.md). 2. **Personal knowledge base** for AI and software-engineering practice — research observations live under `docs/`, with promoted rules in instruction files and descriptive notes in `docs/knowledge/`. -This repo is not a product application. There is no build, no package manager, and no test runner. Edits are almost always markdown. +This repo is not a product application. There is no build and no package manager; the doc-quality checks below are its test suite. Edits are almost always markdown. ## Architecture: layered instruction files @@ -73,7 +73,7 @@ for f in AGENTS.md CLAUDE.md BOOTSTRAP.md \ done ``` -The secrets, file-length, and Boundaries checks should print nothing. The cross-ref grep is informational — each line should point at an existing file; manually verify any new ones. +The file-length and Boundaries checks should print nothing. The secrets and cross-ref greps are informational — instruction files legitimately contain words like "secret" in rules, so review hits rather than treating any output as failure. ### Tier 2 — markdown lint @@ -81,7 +81,7 @@ The secrets, file-length, and Boundaries checks should print nothing. The cross- npx markdownlint-cli2 "**/*.md" "#node_modules" ``` -Configure via `.markdownlint.json` at the repo root. Suggested baseline: +Configured via `.markdownlint.json` at the repo root: ```json { @@ -101,7 +101,7 @@ lychee --offline '**/*.md' # relative links only, fast lychee '**/*.md' # adds external URL probes, network-bound ``` -Add `lychee.toml` to allowlist intentionally unreachable URLs (e.g., the `` placeholder in `BOOTSTRAP.md`). +`lychee.toml` at the repo root allowlists intentionally unreachable URLs (e.g., the `` placeholder in `BOOTSTRAP.md`) so the weekly online run does not file false-positive issues. ### Tier 4 — spell check diff --git a/README.md b/README.md index d4bad86..a2d749c 100644 --- a/README.md +++ b/README.md @@ -33,13 +33,15 @@ Operating model for adding to the knowledge base: ## Current research sources -The live, authoritative list lives in [`docs/source-repos.md`](./docs/source-repos.md) — 12 sources tracked at last count, each with status (`pending` / `extracted` / `promoted` / `rejected`), the practices we use them for, and a URL. +The live, authoritative list lives in [`docs/source-repos.md`](./docs/source-repos.md) — every source carries a status (`pending` / `extracted` / `promoted` / `rejected`), the practices we use it for, and a URL. Highlights so far: - **Skill conventions** — Anthropic Agent Skills, `google/skills`, `bytedance/deer-flow`, `forrestchang/andrej-karpathy-skills`. - **Cross-agent baselines** — the `AGENTS.md` spec, `openai/codex` AGENTS.md, `alchaincyf/huashu-design`, `garrytan/gstack`, `SuperClaude-Org/SuperClaude_Framework`. - **Per-host instruction formats** — Anthropic Claude Code memory docs, GitHub Copilot custom instructions, `github/awesome-copilot`. +- **Engineering methods** — Thoughtworks Structured-Prompt-Driven Development, Martin Fowler's Fragments on verification and harness engineering. +- **Integration patterns** — `chenhg5/cc-connect` bridge-daemon and adapter conventions. Add new sources by following the [research handling workflow](./AGENTS.md#research-handling): row in `source-repos.md`, observation in `docs/research-log.md`, then promote stable practices. diff --git a/docs/ai-agent-coding-strategy.md b/docs/ai-agent-coding-strategy.md index 5effa02..f70a8b6 100644 --- a/docs/ai-agent-coding-strategy.md +++ b/docs/ai-agent-coding-strategy.md @@ -25,19 +25,28 @@ Agents pick up different files. Place each rule at the narrowest layer that stil | Layer | File(s) | Loaded when | Use for | |---|---|---|---| | Universal baseline | `AGENTS.md` | Codex, Cursor, Aider, Jules, OpenHands sessions | Rules every agent should follow | -| Claude project memory | `CLAUDE.md` | Every Claude Code session | Claude-specific addenda + `@AGENTS.md` import | +| Claude project memory | `CLAUDE.md` | Every Claude Code session | Claude-specific addenda + cross-reference to `AGENTS.md` | | Claude path rules | `.claude/rules/*.md` with `paths:` frontmatter | When matching files are edited | Topic- or path-scoped Claude rules | | Copilot repo-wide | `.github/copilot-instructions.md` | Every Copilot interaction | Build, test, and PR rules for Copilot | | Copilot path rules | `.github/instructions/*.instructions.md` with `applyTo:` | When matching files are referenced | Tech- or path-scoped Copilot rules | | Skills | `SKILL.md` directories | On-demand when triggered | Reusable capability packages | -| Human strategy | `docs/*.md` | Read by humans and on request by agents | Background, rationale, research | +| Human strategy | `docs/*.md` (incl. `docs/knowledge/`) | Read by humans and on request by agents | Background, rationale, research, descriptive notes | + +## Single source, multi-host + +When the same content needs to reach multiple agents, keep one canonical source and emit several delivery files rather than maintaining parallel copies. + +- Pick one canonical file per topic. Examples: `AGENTS.md` for the cross-agent baseline; a `SKILL.md` body for a capability bundle. +- Emit per-host delivery files that wrap or link to the canonical: `CLAUDE.md` cross-references `AGENTS.md`; `.github/copilot-instructions.md` restates the parts Copilot needs; `.cursor/rules/*.mdc` carries the same content for Cursor; a plugin manifest packages it for installable distribution. +- Document two install paths for users: a structured install (plugin marketplace, package manager) and an append-mode file-drop (`curl -o CLAUDE.md ` for new repos, `curl >> CLAUDE.md` for existing ones). See `BOOTSTRAP.md` for this repo's implementation. +- When the canonical content changes, list the per-host files that must be updated alongside it. A pre-commit checklist or a CI grep for drift is the safety net. ## Minimum viable workflow For a new repo: 1. Add `AGENTS.md` at the root. -2. Add `CLAUDE.md` with `@AGENTS.md` at the top, plus Claude-specific addenda. +2. Add `CLAUDE.md` that cross-references `AGENTS.md` at the top, plus Claude-specific addenda. A markdown link keeps the baseline out of always-loaded context; `@AGENTS.md` import embeds it — choose per context budget. This repo uses the link. 3. Add `.github/copilot-instructions.md` with the same baseline restated for Copilot. 4. Add `docs/source-repos.md` and `docs/research-log.md` if the project will study external sources. 5. Validate by running each agent on a small task and reviewing whether the rules were honored. @@ -81,20 +90,11 @@ See [`docs/knowledge/structured-prompt-driven-development.md`](./knowledge/struc ## Anti-patterns - Burying critical constraints inside long prose. Agents will skim past them. -- Duplicating the same rule into every agent file. Use `@AGENTS.md` import or restate only what differs. +- Duplicating the same rule into every agent file. Cross-reference the canonical file (link or `@AGENTS.md` import) and restate only what differs. - Treating exploratory research notes as mandatory rules. Keep `docs/research-log.md` separate. - Mixing project-specific examples into general agent rules. - Adding marketing language unless the file is explicitly a sales artifact. -## Single source, multi-host - -When the same content needs to reach multiple agents, keep one canonical source and emit several delivery files rather than maintaining parallel copies. - -- Pick one canonical file per topic. Examples: `AGENTS.md` for the cross-agent baseline; a `SKILL.md` body for a capability bundle. -- Emit per-host delivery files that wrap or link to the canonical: `CLAUDE.md` cross-references `AGENTS.md`; `.github/copilot-instructions.md` restates the parts Copilot needs; `.cursor/rules/*.mdc` carries the same content for Cursor; a plugin manifest packages it for installable distribution. -- Document two install paths for users: a structured install (plugin marketplace, package manager) and an append-mode file-drop (`curl -o CLAUDE.md ` for new repos, `curl >> CLAUDE.md` for existing ones). -- When the canonical content changes, list the per-host files that must be updated alongside it. A pre-commit checklist or a CI grep for drift is the safety net. - ## How rules graduate ```text @@ -116,5 +116,7 @@ Source row in source-repos.md updated to Status = promoted - `CLAUDE.md` — Claude Code project memory. - `.github/copilot-instructions.md` — repo-wide Copilot rules. - `.github/instructions/azure-ai.instructions.md` — Azure-specific Copilot rules. +- `BOOTSTRAP.md` — drop-in install for new repos. - `docs/source-repos.md` — tracked sources. - `docs/research-log.md` — observations and promoted rules. +- `docs/knowledge/` — descriptive notes the practical examples link to. diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000..647e61f --- /dev/null +++ b/lychee.toml @@ -0,0 +1,9 @@ +# Link-check config for lychee (tier 3 locally, doc-quality + weekly online runs in CI). +# Exclude intentionally unreachable URLs so the weekly online run does not file +# false-positive "Link Checker Report" issues. + +exclude = [ + # Placeholder install URL in BOOTSTRAP.md; users substitute their own account. + 'raw\.githubusercontent\.com/', + '', +] diff --git a/scripts/check.sh b/scripts/check.sh index 5147f0e..e359649 100755 --- a/scripts/check.sh +++ b/scripts/check.sh @@ -28,6 +28,14 @@ if [ -n "$missing" ]; then fail=1 fi +# Secrets scan over the staged diff. Informational, not a hard fail: rule files +# legitimately contain words like "secret" — review hits, don't auto-block. +# Cross-reference resolution is tier 3's job (lychee --offline). +hits=$(git diff --cached | grep -iE 'api[_-]?key|secret|token|password' || true) +if [ -n "$hits" ]; then + printf 'i Secret-pattern matches in staged diff (review, not necessarily a failure):\n%s\n' "$hits" +fi + printf '\n** Tier 2 — markdownlint\n' if command -v npx >/dev/null 2>&1; then npx --yes markdownlint-cli2 "**/*.md" "#node_modules" || fail=1