feat(skills): add issue-creation skill, rewrite branch-pr skill, and create AGENTS.md index

Alan-TheGentleman · Alan-TheGentleman · commit 3c0babbac1da · 2026-03-15T21:37:40.000+01:00
- Add engram-issue-creation skill with full template reference and examples
- Rewrite engram-branch-pr skill to reflect enforcement system (v2.0)
- Create AGENTS.md as the skill index with trigger-to-path mapping for all 19 skills
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,34 @@
+# Engram — Agent Skills Index
+
+When working on this project, load the relevant skill(s) BEFORE writing any code.
+
+## How to Use
+
+1. Check the trigger column to find skills that match your current task
+2. Load the skill by reading the SKILL.md file at the listed path
+3. Follow ALL patterns and rules from the loaded skill
+4. Multiple skills can apply simultaneously
+
+## Skills
+
+| Skill | Trigger | Path |
+|-------|---------|------|
+| `engram-architecture-guardrails` | Any change that affects system boundaries, ownership, state flow, or cross-package responsibilities. | [`skills/architecture-guardrails/SKILL.md`](skills/architecture-guardrails/SKILL.md) |
+| `engram-branch-pr` | When creating a pull request, opening a PR, or preparing changes for review. | [`skills/branch-pr/SKILL.md`](skills/branch-pr/SKILL.md) |
+| `engram-business-rules` | Any change that affects sync behavior, project controls, permissions, or memory semantics. | [`skills/business-rules/SKILL.md`](skills/business-rules/SKILL.md) |
+| `engram-commit-hygiene` | Any commit creation, review, or branch cleanup. | [`skills/commit-hygiene/SKILL.md`](skills/commit-hygiene/SKILL.md) |
+| `engram-cultural-norms` | Starting substantial work, reviewing changes, or defining team conventions. | [`skills/cultural-norms/SKILL.md`](skills/cultural-norms/SKILL.md) |
+| `engram-dashboard-htmx` | Any change to htmx attributes, partial updates, forms, or server-rendered browser UI. | [`skills/dashboard-htmx/SKILL.md`](skills/dashboard-htmx/SKILL.md) |
+| `engram-docs-alignment` | Any code or workflow change that affects user or contributor behavior. | [`skills/docs-alignment/SKILL.md`](skills/docs-alignment/SKILL.md) |
+| `engram-issue-creation` | When creating a GitHub issue, reporting a bug, or requesting a feature. | [`skills/issue-creation/SKILL.md`](skills/issue-creation/SKILL.md) |
+| `engram-memory-protocol` | Decisions, bugfixes, discoveries, preferences, or session closure. | [`skills/memory-protocol/SKILL.md`](skills/memory-protocol/SKILL.md) |
+| `engram-plugin-thin` | Changes in plugin scripts/hooks for Claude, OpenCode, Gemini, or Codex. | [`skills/plugin-thin/SKILL.md`](skills/plugin-thin/SKILL.md) |
+| `engram-pr-review-deep` | Reviewing any external or internal contribution before merge. | [`skills/pr-review-deep/SKILL.md`](skills/pr-review-deep/SKILL.md) |
+| `engram-project-structure` | Creating files, packages, handlers, templates, styles, or tests in this repo. | [`skills/project-structure/SKILL.md`](skills/project-structure/SKILL.md) |
+| `engram-sdd-flow` | When user requests SDD or multi-phase implementation planning. | [`skills/sdd-flow/SKILL.md`](skills/sdd-flow/SKILL.md) |
+| `engram-server-api` | Any route, handler, payload, or status code modification. | [`skills/server-api/SKILL.md`](skills/server-api/SKILL.md) |
+| `engram-testing-coverage` | When implementing behavior changes in any package. | [`skills/testing-coverage/SKILL.md`](skills/testing-coverage/SKILL.md) |
+| `engram-tui-quality` | Changes in model, update, view, navigation, or rendering. | [`skills/tui-quality/SKILL.md`](skills/tui-quality/SKILL.md) |
+| `engram-ui-elements` | Adding or changing dashboard UI components or connected browsing flows. | [`skills/ui-elements/SKILL.md`](skills/ui-elements/SKILL.md) |
+| `engram-visual-language` | Any dashboard styling, typography, spacing, or visual identity change. | [`skills/visual-language/SKILL.md`](skills/visual-language/SKILL.md) |
+| `gentleman-bubbletea` | When editing Go files in installer/internal/tui/, working on TUI screens, or adding new UI features. | [`skills/gentleman-bubbletea/SKILL.md`](skills/gentleman-bubbletea/SKILL.md) |
diff --git a/skills/branch-pr/SKILL.md b/skills/branch-pr/SKILL.md
@@ -1,48 +1,172 @@
 ---
 name: engram-branch-pr
 description: >
-  Branch and PR workflow for Engram contributors.
-  Trigger: When starting any change that will be proposed through GitHub.
+  PR creation workflow for Engram following the issue-first enforcement system.
+  Trigger: When creating a pull request, opening a PR, or preparing changes for review.
 license: Apache-2.0
 metadata:
   author: gentleman-programming
-  version: "1.0"
+  version: "2.0"
 ---
 
 ## When to Use
 
 Use this skill when:
-- Starting a new feature, fix, or refactor
-- Splitting work into multiple PRs
-- Preparing a PR for review and merge
+- Creating a pull request for any change
+- Preparing a branch for submission
+- Helping a contributor open a PR
 
 ---
 
-## Core Rules
+## Critical Rules
 
-1. Create a focused branch (`feat/*`, `fix/*`, `chore/*`).
-2. Keep one logical scope per branch.
-3. Push early and often to avoid large risky diffs.
-4. Open PRs with intent, risk, and validation evidence.
-5. Do not mix unrelated changes in the same PR.
+1. **Every PR MUST link an approved issue** — no exceptions
+2. **Every PR MUST have exactly one `type:*` label**
+3. **5 automated checks must pass** before merge is possible
+4. **Blank PRs without issue linkage will be blocked** by GitHub Actions
 
 ---
 
-## PR Structure
+## Workflow
 
-Include:
-- Problem statement (why this change exists)
-- Solution summary (what changed)
-- Risk notes (what could break)
-- Validation (tests/commands executed)
-- Follow-ups (what is intentionally out of scope)
+```
+1. Verify issue has `status:approved` label
+2. Create branch: feat/*, fix/*, docs/*, refactor/*, chore/*
+3. Implement changes
+4. Run tests locally (unit + e2e)
+5. Open PR using the template
+6. Add exactly one type:* label
+7. Wait for 5 automated checks to pass
+```
 
 ---
 
-## Merge Checklist
+## Branch Naming
 
-- [ ] Branch name matches scope
-- [ ] Diff is focused and reviewable
-- [ ] Tests relevant to the change pass
-- [ ] No temporary files or local artifacts included
-- [ ] PR description explains why, not only what
+| Type | Branch pattern | Example |
+|------|---------------|---------|
+| Bug fix | `fix/<short-description>` | `fix/duplicate-observation-insert` |
+| Feature | `feat/<short-description>` | `feat/json-export-command` |
+| Docs | `docs/<short-description>` | `docs/api-reference-update` |
+| Refactor | `refactor/<short-description>` | `refactor/extract-query-sanitizer` |
+| Chore | `chore/<short-description>` | `chore/bump-bubbletea-v0.26` |
+
+---
+
+## PR Body Format
+
+The PR template is at `.github/PULL_REQUEST_TEMPLATE.md`. Every PR body MUST contain:
+
+### 1. Linked Issue (REQUIRED)
+
+```markdown
+Closes #<issue-number>
+```
+
+Valid keywords: `Closes #N`, `Fixes #N`, `Resolves #N` (case insensitive).
+The linked issue MUST have the `status:approved` label.
+
+### 2. PR Type (REQUIRED)
+
+Check exactly ONE in the template and add the matching label:
+
+| Checkbox | Label to add |
+|----------|-------------|
+| Bug fix | `type:bug` |
+| New feature | `type:feature` |
+| Documentation only | `type:docs` |
+| Code refactoring | `type:refactor` |
+| Maintenance/tooling | `type:chore` |
+| Breaking change | `type:breaking-change` |
+
+### 3. Summary
+
+1-3 bullet points of what the PR does.
+
+### 4. Changes Table
+
+```markdown
+| File | Change |
+|------|--------|
+| `path/to/file` | What changed |
+```
+
+### 5. Test Plan
+
+```markdown
+- [x] Unit tests pass locally: `go test ./...`
+- [x] E2E tests pass locally: `go test -tags e2e ./internal/server/...`
+- [x] Manually tested the affected functionality
+```
+
+### 6. Contributor Checklist
+
+All boxes must be checked:
+- Linked an approved issue
+- Added exactly one `type:*` label
+- Ran unit tests locally
+- Ran e2e tests locally
+- Docs updated if behavior changed
+- Conventional commit format
+- No `Co-Authored-By` trailers
+
+---
+
+## Automated Checks (all 5 must pass)
+
+| Check | Job name | What it verifies |
+|-------|----------|-----------------|
+| PR Validation | `Check Issue Reference` | Body contains `Closes/Fixes/Resolves #N` |
+| PR Validation | `Check Issue Has status:approved` | Linked issue has `status:approved` |
+| PR Validation | `Check PR Has type:* Label` | PR has exactly one `type:*` label |
+| CI | `Unit Tests` | `go test ./...` passes |
+| CI | `E2E Tests` | `go test -tags e2e ./internal/server/...` passes |
+
+---
+
+## Conventional Commits
+
+```
+<type>(<scope>): <short description>
+```
+
+Type-to-label mapping:
+
+| Commit type | PR label |
+|-------------|----------|
+| `feat` | `type:feature` |
+| `fix` | `type:bug` |
+| `docs` | `type:docs` |
+| `refactor` | `type:refactor` |
+| `chore` | `type:chore` |
+| `feat!` / `fix!` | `type:breaking-change` |
+
+Examples:
+```
+feat(cli): add --json flag to session list command
+fix(store): prevent duplicate observation insert on retry
+docs(contributing): update workflow documentation
+refactor(internal): extract search query sanitizer
+chore(deps): bump github.com/charmbracelet/bubbletea to v0.26
+fix!: change session ID format
+```
+
+---
+
+## Commands
+
+```bash
+# Create branch
+git checkout -b feat/my-feature main
+
+# Run tests before pushing
+go test ./...                                    # unit tests
+go test -tags e2e ./internal/server/...          # e2e tests
+
+# Push and create PR
+git push -u origin feat/my-feature
+gh pr create --title "feat(scope): description" --body "Closes #N"
+
+# Add type label to PR
+gh pr edit <pr-number> --add-label "type:feature"
+```
diff --git a/skills/issue-creation/SKILL.md b/skills/issue-creation/SKILL.md
