Skip to content

Commit 3f2f3c9

Browse files
zircotezircote
committed
feat: add agent instruction files for Copilot, Claude, and all runtimes
- .github/copilot-instructions.md: Copilot-specific instructions covering project structure, daily pipeline, safe-output constraints, branching, tracked repos, and critical gh-aw rules - AGENTS.md: Generic agent instructions read by all runtimes (Copilot, Claude, Codex, gh-aw workflows) - CLAUDE.md: Project-level Claude Code instructions with quality gates, commands, compiler usage, and spec resources
1 parent 45ab08c commit 3f2f3c9

3 files changed

Lines changed: 231 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Copilot Instructions — aw-author Plugin
2+
3+
## Project Identity
4+
5+
This is the **aw-author** Claude Code plugin (v1.3.0) for authoring, validating, and maintaining GitHub Agentic Workflow (gh-aw) markdown files. The repository lives at `zircote/github-agentic-workflows`.
6+
7+
gh-aw workflows are markdown files with YAML frontmatter in `.github/workflows/`, compiled to `.lock.yml` via `gh aw compile`. This plugin provides the reference materials, skills, and automated pipelines that keep those workflows correct and current.
8+
9+
## Repository Structure
10+
11+
```
12+
commands/ Slash command entry points (/aw-author, /aw-daily, /aw-merge, /aw-report, /aw-status, /aw-upgrade)
13+
skills/
14+
aw-author/ Authoring skill + 9 reference files (the canonical gh-aw spec subset)
15+
aw-daily/ Autonomous daily pipeline skill + gap analysis references
16+
gh-aw-report/ Intelligence reporting skill + knowledge base + search queries
17+
agents/
18+
aw-analyst.md Deep analysis agent for workflow review
19+
.github/workflows/
20+
daily-intelligence.md Daily autonomous pipeline (gh-aw, fuzzy schedule)
21+
daily-intelligence.lock.yml Compiled workflow (DO NOT EDIT)
22+
weekly-develop-merge.md Weekly develop→main merge (gh-aw, fuzzy schedule)
23+
weekly-develop-merge.lock.yml Compiled workflow (DO NOT EDIT)
24+
outputs/gh-aw-reports/ Dated intelligence reports
25+
```
26+
27+
## Branching Strategy
28+
29+
- **`main`** — stable, production branch
30+
- **`develop`** — daily automated updates land here via PR
31+
- **`daily-intelligence-YYYY-MM-DD`** — ephemeral feature branches created by `/aw-daily`, deleted after merge to `develop`
32+
- Weekly: `develop` merges to `main` via `/aw-merge` (squash merge, then develop resets to main)
33+
34+
## Daily Pipeline (`.github/workflows/daily-intelligence.md`)
35+
36+
This workflow runs daily around 07:00 (fuzzy schedule) and executes:
37+
38+
1. **Research** — web fetch + GitHub API queries on 5 tracked repos (`github/gh-aw`, `github/github-mcp-server`, `github/copilot-cli`, `githubnext/agentics`, `zircote/github-agentic-workflows`)
39+
2. **Knowledge base update** — append stable facts to `skills/gh-aw-report/knowledge-base.md`
40+
3. **Discussion posting** — post report to Discussions in the "Project News" category
41+
4. **Gap analysis** — compare findings against 11 reference files in `skills/aw-author/references/` and `skills/gh-aw-report/references/`
42+
5. **Issue creation** — file issues for identified gaps (max 5 per run, dedup by `[aw-daily]` prefix)
43+
6. **Implementation** — edit reference files on a branch from `develop`
44+
7. **PR creation** — PR to `develop` with `Closes #NNN` links
45+
8. **Summary** — report what changed
46+
47+
### Idempotency
48+
49+
The pipeline checks before running:
50+
- Discussion titled `"gh-aw Intelligence Report — {today}"` already exists → skip research
51+
- PR with branch `daily-intelligence-{today}` exists → skip entirely
52+
- Issue with `[aw-daily]` prefix matching a gap → skip that issue
53+
54+
### Safe-Output Constraints
55+
56+
All write operations go through safe-outputs:
57+
- `create-discussion`: title-prefix `"gh-aw Intelligence Report — "`, category `"project news"`, max 1
58+
- `create-issue`: title-prefix `"[aw-daily] "`, labels `[automated, reference-update]`, max 5
59+
- `create-pull-request`: title-prefix `"docs(references): "`, base-branch `develop`, max 1
60+
- `push-to-pull-request-branch`: target `"*"`, title-prefix `"docs(references): "`, labels `[automated]`, max 10
61+
- `add-comment`: `discussions: false`, max 3
62+
- `add-labels`: allowed `[automated, reference-update, intelligence]`, max 5
63+
64+
## Weekly Merge (`.github/workflows/weekly-develop-merge.md`)
65+
66+
Runs weekly on Monday around 09:00. Checks if `develop` is ahead of `main`, creates a PR if so. Does NOT auto-merge — merge follows repository policy.
67+
68+
## Reference Files — The Source of Truth
69+
70+
The 9 files in `skills/aw-author/references/` are the canonical gh-aw specification subset for this plugin. They are the primary target of the daily pipeline's gap analysis and updates:
71+
72+
| File | Content |
73+
|------|---------|
74+
| `frontmatter-schema.md` | Complete YAML frontmatter field reference (~2100 lines) |
75+
| `safe-outputs.md` | All safe-output types, parameters, constraints (~850 lines) |
76+
| `tools-reference.md` | Tool types and configuration (~470 lines) |
77+
| `production-gotchas.md` | Runtime gotchas verified through production debugging (~380 lines) |
78+
| `orchestration.md` | 7 orchestration patterns + engine model selection (~325 lines) |
79+
| `examples.md` | 5 annotated example workflows + minimal template (~430 lines) |
80+
| `validation.md` | Validation checklist, anti-patterns, debugging (~230 lines) |
81+
| `markdown-body.md` | Prose body writing guide + instruction files (~320 lines) |
82+
| `llms-resources.md` | Fetchable spec URLs (~87 lines) |
83+
84+
## Critical Rules
85+
86+
1. **Never edit `.lock.yml` files** — they are generated by `gh aw compile`
87+
2. **`add-comment` safe-outputs must include `discussions: false`** — omitting this causes HTTP 422 when the App lacks Discussions permission
88+
3. **`plugins:` frontmatter field is DEPRECATED** — use `dependencies:` and run `gh aw fix --write`
89+
4. **Write permissions are NOT allowed in `permissions:` block** — the compiler rejects them; all writes go through safe-outputs
90+
5. **Trigger field is `issues` (plural), not `issue`**
91+
6. **Event-triggered workflows need `reaction: eyes`** in the `on:` block
92+
7. **`${{ }}` expressions in fenced code blocks are NOT interpolated** — use env vars instead
93+
8. **Knowledge base is append-only** — mark superseded entries with `[SUPERSEDED by YYYY-MM-DD]`, never delete
94+
9. **Section headers are anchors, not line numbers** — the daily pipeline uses headers to locate edit targets because line numbers shift between runs
95+
96+
## GitHub Discussion Category
97+
98+
Reports post to the **Project News** category:
99+
- Category ID: `DIC_kwDORSXBr84C61Lr`
100+
- Repository: `zircote/github-agentic-workflows`
101+
102+
## Tracked Repositories for Activity Queries
103+
104+
| Repository | What to Extract |
105+
|-----------|-----------------|
106+
| `github/gh-aw` | New features, breaking changes, bug reports, version bumps |
107+
| `github/github-mcp-server` | Version changes, new tools, breaking changes |
108+
| `github/copilot-cli` | CLI updates, new agent modes |
109+
| `githubnext/agentics` | New sample workflows, pattern changes |
110+
| `zircote/github-agentic-workflows` | Self-referential activity |

‎AGENTS.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Agent Instructions — aw-author Plugin
2+
3+
This file is read by all agentic runtimes (GitHub Copilot, Claude Code, Codex, and gh-aw workflows) when operating in this repository.
4+
5+
## What This Repository Is
6+
7+
The **aw-author** plugin (v1.3.0) for Claude Code. It provides skills, commands, and reference materials for authoring GitHub Agentic Workflow (gh-aw) markdown files, plus an autonomous daily pipeline that keeps the reference materials current.
8+
9+
**Repository**: `zircote/github-agentic-workflows`
10+
**Owner**: Robert Allen (`zircote`)
11+
12+
## Key Directories
13+
14+
- `skills/aw-author/references/` — 9 canonical reference files (frontmatter schema, safe-outputs, tools, gotchas, patterns, examples, validation, body guide, URLs). These are the primary deliverable of this project.
15+
- `skills/aw-daily/` — Autonomous daily pipeline skill that researches the gh-aw ecosystem, identifies gaps in reference files, and creates PRs to fix them.
16+
- `skills/gh-aw-report/` — Intelligence reporting skill with knowledge base and search queries.
17+
- `.github/workflows/` — Two gh-aw workflows: `daily-intelligence.md` (daily research + updates) and `weekly-develop-merge.md` (weekly develop→main merge).
18+
- `outputs/gh-aw-reports/` — Dated intelligence reports.
19+
20+
## Branching
21+
22+
- `main` — stable
23+
- `develop` — receives daily automated PRs from the intelligence pipeline
24+
- Feature branches: `daily-intelligence-YYYY-MM-DD` (ephemeral, deleted after merge)
25+
26+
## Rules for All Agents
27+
28+
1. **Never edit `.lock.yml` files.** They are compiled output from `gh aw compile`.
29+
2. **Reference files are large (200–2100 lines).** Use section headers as anchors for edits, not line numbers.
30+
3. **Knowledge base (`skills/gh-aw-report/knowledge-base.md`) is append-only.** Never delete entries. Mark outdated facts with `[SUPERSEDED by YYYY-MM-DD]`.
31+
4. **All `add-comment` safe-outputs must include `discussions: false`.** This is a known gh-aw gotcha that causes HTTP 422 errors.
32+
5. **The `plugins:` frontmatter field is deprecated.** Use `dependencies:` instead. Run `gh aw fix --write` to migrate.
33+
6. **Discussion posts go to the "Project News" category** (ID: `DIC_kwDORSXBr84C61Lr`).
34+
7. **The daily pipeline is idempotent.** It checks for existing Discussions, PRs, and issues before creating new ones. Re-running on the same day is safe.
35+
8. **When editing reference files, verify the change compiles.** Run `gh aw compile` after modifying any `.md` file in `.github/workflows/`.
36+
37+
## gh-aw Spec Essentials
38+
39+
- Workflows are `.md` files with YAML frontmatter in `.github/workflows/`
40+
- Compiled to `.lock.yml` via `gh aw compile`
41+
- `permissions:` block is **read-only** — write permissions are rejected by the compiler
42+
- All write operations go through `safe-outputs:` using App tokens
43+
- Event-triggered workflows need `reaction: eyes` in the `on:` block
44+
- `${{ }}` expressions inside fenced code blocks are NOT interpolated — use env vars
45+
- Trigger is `issues` (plural), not `issue`
46+
47+
## Available Commands
48+
49+
| Command | Purpose |
50+
|---------|---------|
51+
| `/aw-author` | Author, validate, improve, or debug gh-aw workflows |
52+
| `/aw-daily` | Autonomous daily pipeline (research → gaps → fix → PR) |
53+
| `/aw-merge` | Weekly develop→main merge |
54+
| `/aw-report` | Intelligence sweep + Discussion posting |
55+
| `/aw-status` | Quick briefing from knowledge base |
56+
| `/aw-upgrade` | Upgrade gh-aw extension + recompile + PR |

‎CLAUDE.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# CLAUDE.md — aw-author Plugin
2+
3+
## Project
4+
5+
The **aw-author** Claude Code plugin (v1.3.0) at `zircote/github-agentic-workflows`. Provides skills, commands, and reference materials for GitHub Agentic Workflow (gh-aw) authoring, plus an autonomous daily intelligence pipeline.
6+
7+
## Commands
8+
9+
- `/aw-author` — Author, validate, improve, debug gh-aw workflow files
10+
- `/aw-daily [--dry-run] [--skip-research] [--skip-implementation] [--no-merge]` — Autonomous daily pipeline: research → Discussion → gap analysis → implementation → PR to `develop`
11+
- `/aw-merge [--dry-run] [--no-reset]` — Weekly develop→main merge
12+
- `/aw-report [--deep] [--no-post] [--domains ...]` — Intelligence sweep + Discussion posting
13+
- `/aw-status [--domain ...] [--since ...]` — Quick KB briefing
14+
- `/aw-upgrade [--force] [--dry-run] [--no-merge] [--strict]` — gh-aw extension upgrade cycle
15+
16+
## Branching
17+
18+
- `main` — stable production
19+
- `develop` — receives daily automated PRs
20+
- `daily-intelligence-YYYY-MM-DD` — ephemeral feature branches
21+
22+
## Quality Gates
23+
24+
This project has no linter, type checker, or test suite. Quality gates are:
25+
26+
1. **`gh aw compile`** — all `.md` workflows in `.github/workflows/` must compile to `.lock.yml` with 0 errors
27+
2. **`gh aw validate`** — all compiled workflows must validate with 0 errors
28+
3. **Cross-reference consistency** — facts mentioned in one reference file must be consistent across all files that reference them
29+
30+
After editing any `.github/workflows/*.md` file, always recompile with `gh aw compile` and verify 0 errors.
31+
32+
## Key Files
33+
34+
| Path | Role |
35+
|------|------|
36+
| `skills/aw-author/references/` | 9 canonical reference files — the core deliverable |
37+
| `skills/aw-daily/SKILL.md` | 9-phase autonomous pipeline |
38+
| `skills/gh-aw-report/knowledge-base.md` | Persistent append-only KB |
39+
| `.github/workflows/daily-intelligence.md` | Primary daily gh-aw workflow |
40+
| `.github/workflows/weekly-develop-merge.md` | Weekly merge gh-aw workflow |
41+
| `.claude-plugin/plugin.json` | Plugin manifest |
42+
43+
## Critical Conventions
44+
45+
- **`.lock.yml` files are generated** — never edit them directly
46+
- **`add-comment` must include `discussions: false`** — known gotcha causing HTTP 422
47+
- **`plugins:` is deprecated** — use `dependencies:`, run `gh aw fix --write`
48+
- **Knowledge base is append-only** — mark old entries `[SUPERSEDED by YYYY-MM-DD]`
49+
- **Use section headers as edit anchors** — not line numbers (they shift between runs)
50+
- **Discussion category ID**: `DIC_kwDORSXBr84C61Lr` (Project News)
51+
52+
## gh-aw Compiler
53+
54+
```bash
55+
gh aw compile .github/workflows/<name>.md # Compile one workflow
56+
gh aw validate .github/workflows/<name>.md # Validate one workflow
57+
gh aw compile # Compile all workflows
58+
gh aw version # v0.68.1
59+
```
60+
61+
## Spec Resources
62+
63+
- Full spec: `https://github.github.com/gh-aw/llms-full.txt`
64+
- Abridged: `https://github.github.com/gh-aw/llms-small.txt`
65+
- Patterns: `https://github.github.com/gh-aw/_llms-txt/agentic-workflows.txt`

0 commit comments

Comments
 (0)