Skip to content

feat: add feature-map skill #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
markphelps merged 1 commit into from
Sep 24, 2026
Merged

feat: add feature-map skill #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@ Reusable agent plugins and skills following AGENTS/skills conventions.

## Plugins

| Plugin | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [vault](./vault/) | Zettelkasten-style vault workflows for Obsidian notes |
| [development](./development/) | Agent context, PR fixups, CLI design, codebase-grounded landing copy, architecture mapping and whiteboard defense, OSS readiness and marketing, session log audits, bug verification, decision records, and self-hosted runners |
| Plugin | Description |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [vault](./vault/) | Zettelkasten-style vault workflows for Obsidian notes |
| [development](./development/) | Agent context, PR fixups, CLI design, codebase-grounded landing copy, architecture mapping and whiteboard defense, OSS readiness and marketing, session log audits, feature maps, bug verification, decision records, and self-hosted runners |

## Layout

Expand Down
17 changes: 12 additions & 5 deletions development/.codex-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "development",
"version": "0.0.9",
"description": "Developer workflow skills for agent context, PR fixups, CLI design, codebase-grounded landing copy, architecture mapping and whiteboard defense, OSS readiness, OSS marketing, session log audits, bug verification, decision records, and GitHub Actions self-hosted runners.",
"version": "0.0.10",
"description": "Developer workflow skills for agent context, PR fixups, CLI design, codebase-grounded landing copy, architecture mapping and whiteboard defense, OSS readiness, OSS marketing, session log audits, agent feature maps, bug verification, decision records, and GitHub Actions self-hosted runners.",
"author": {
"name": "Mark Phelps"
},
Expand Down Expand Up @@ -45,13 +45,19 @@
"verify-bug",
"bug-verification",
"false-positives",
"triage"
"triage",
"feature-map",
"verification",
"qa",
"e2e",
"playwright",
"accessibility"
],
"skills": "./skills/",
"interface": {
"displayName": "Development",
"shortDescription": "Agent context, PR fixup, CLI design, landing copy, architecture mapping and whiteboard defense, OSS readiness, marketing, session log audit, bug verification, decision records, and runner workflows",
"longDescription": "Development workflow skills for auditing agent context files, fixing existing GitHub PRs, designing humane command-line interfaces, writing product landing-page copy backed by shipped code, mapping codebase architecture and design rationale, preparing GitHub repos for open source release, sharpening OSS README positioning, mining local agent session logs for papercuts in your own tools, verifying whether claimed bugs are real, writing and maintaining decision and plan records (ADRs), and running GitHub Actions self-hosted runners on a Linux host.",
"shortDescription": "Agent context, PR fixup, CLI design, landing copy, architecture mapping and whiteboard defense, OSS readiness, marketing, session log audit, feature maps, bug verification, decision records, and runner workflows",
"longDescription": "Development workflow skills for auditing agent context files, fixing existing GitHub PRs, designing humane command-line interfaces, writing product landing-page copy backed by shipped code, mapping codebase architecture and design rationale, preparing GitHub repos for open source release, sharpening OSS README positioning, mining local agent session logs for papercuts in your own tools, building feature maps that let agents drive and verify an app, verifying whether claimed bugs are real, writing and maintaining decision and plan records (ADRs), and running GitHub Actions self-hosted runners on a Linux host.",
"developerName": "Mark Phelps",
"category": "Development",
"capabilities": ["Read", "Write"],
Expand All @@ -64,6 +70,7 @@
"Map this codebase into a layered architecture overview.",
"Quiz me whiteboard-defense style on this system's flows, trade-offs, and failure modes.",
"Turn this codebase map into doc and comment fixes on a branch.",
"Build a feature map so agents can drive and verify this app.",
"Write landing-page copy for this product using only capabilities proven by its codebase.",
"Fact-check this product pitch against the code that actually ships and provide an evidence table.",
"Audit this repo for open source readiness and first-contributor friction.",
Expand Down
5 changes: 5 additions & 0 deletions development/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ agent context.
capabilities that are proven by shipped code
- `context-file-tuneup`: audit and rewrite `CLAUDE.md` / `AGENTS.md` files so
they stay short, specific, and grounded in the repo
- `feature-map`: build a repo-local verification skill listing each
user-facing feature, how to reach and drive it, and what to observe
- `decision-records`: write or update decision and implementation-plan records
(ADRs) in a repo's records directory, keep the registry table in sync, and
preserve history through amendments and supersession
Expand Down Expand Up @@ -57,6 +59,9 @@ agent context.
evidence, keep defense records local under `.map/`, and never modify the
working tree. `/whiteboard docs` writes only to a worktree branch, keeps
source edits to a comments-only commit, and pushes only on confirmation.
- For feature maps, record only drive steps observed to work, drive local or
development environments only, never write secret values, and write only
inside the generated skill directory.
- For bug verification, never touch the working tree (repros run only in a
`git worktree` under `.verify/`), never fix code or open issues, and post
verdicts to GitHub only after the user confirms each post.
Expand Down
35 changes: 20 additions & 15 deletions development/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,25 @@
Developer workflow skills for repo-facing agent context, GitHub PR follow-up,
command-line interface design, codebase-grounded landing copy, architecture
mapping and whiteboard defense, open source release preparation, audits of your
own agent session logs, bug-claim verification, decision records, and GitHub
Actions self-hosted runners.
own agent session logs, agent feature maps, bug-claim verification, decision
records, and GitHub Actions self-hosted runners.

## Skill Set

| Skill | What It Does | When to Invoke |
| --------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cli-design` | Designs and reviews command-line interfaces using clig.dev guidance. | When creating CLI commands, flags, help text, output contracts, error messages, or destructive workflows. |
| `codebase-landing-copy` | Writes product landing-page copy grounded in shipped code and an evidence ledger. | When writing or fact-checking landing pages, homepages, product pitches, hero copy, or store listings for a repo-backed product. |
| `context-file-tuneup` | Audits, rewrites, and tightens `CLAUDE.md` / `AGENTS.md` context files. | When reviewing, shrinking, restructuring, or improving agent context. |
| `decision-records` | Writes and maintains decision and plan records (ADRs) and their registry table, preserving history. | When recording an architecture, product, design, or dependency decision, amending or superseding a record, or starting a records directory. |
| `github-pr-fixup` | Addresses unresolved GitHub PR review comments and failing CI on the existing source branch. | When a user gives you an existing PR URL and wants review feedback or CI failures fixed without a new PR. |
| `github-self-hosted-runner` | Installs, registers, verifies, or removes namespaced GitHub Actions self-hosted runners on a Linux host. | When a user gives a repository or organization URL and wants a persistent runner managed by systemd. |
| `whiteboard` | Maps architecture and design rationale, then runs whiteboard-defense quizzes. | When the user explicitly invokes `/whiteboard` to map a codebase, explore a region, refresh a map, defend their understanding, or write fixes back to the repo's docs. |
| `verify-bug` | Rules on whether claimed bugs are real via an isolated Prover/Skeptic/Referee hearing. | When the user asks whether a bug is real, wants findings or review comments verified, or points at suspected bugs from a map. |
| `oss-marketing` | Sharpens README and public-doc positioning for first-time visitors. | When a repo needs launch copy, clearer positioning, or a README that explains what the project is. |
| `oss-repo-readiness` | Audits and prepares a repo for open source release, focused on developer experience. | When making a repo public, writing CONTRIBUTING or issue templates, or running a pre-launch checklist. |
| `session-log-audit` | Mines local agent session logs for papercuts and produces a ranked fix list. | When the user wants to know what is annoying about their own tool, or why they work around it. |
| Skill | What It Does | When to Invoke |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cli-design` | Designs and reviews command-line interfaces using clig.dev guidance. | When creating CLI commands, flags, help text, output contracts, error messages, or destructive workflows. |
| `codebase-landing-copy` | Writes product landing-page copy grounded in shipped code and an evidence ledger. | When writing or fact-checking landing pages, homepages, product pitches, hero copy, or store listings for a repo-backed product. |
| `context-file-tuneup` | Audits, rewrites, and tightens `CLAUDE.md` / `AGENTS.md` context files. | When reviewing, shrinking, restructuring, or improving agent context. |
| `decision-records` | Writes and maintains decision and plan records (ADRs) and their registry table, preserving history. | When recording an architecture, product, design, or dependency decision, amending or superseding a record, or starting a records directory. |
| `feature-map` | Builds a repo-local verification skill mapping each feature's reach, drive steps, expected results, and gotchas. | When the user explicitly invokes `/feature-map` to build, refresh, or extend an app's feature map. |
| `github-pr-fixup` | Addresses unresolved GitHub PR review comments and failing CI on the existing source branch. | When a user gives you an existing PR URL and wants review feedback or CI failures fixed without a new PR. |
| `github-self-hosted-runner` | Installs, registers, verifies, or removes namespaced GitHub Actions self-hosted runners on a Linux host. | When a user gives a repository or organization URL and wants a persistent runner managed by systemd. |
| `whiteboard` | Maps architecture and design rationale, then runs whiteboard-defense quizzes. | When the user explicitly invokes `/whiteboard` to map a codebase, explore a region, refresh a map, defend their understanding, or write fixes back to the repo's docs. |
| `verify-bug` | Rules on whether claimed bugs are real via an isolated Prover/Skeptic/Referee hearing. | When the user asks whether a bug is real, wants findings or review comments verified, or points at suspected bugs from a map. |
| `oss-marketing` | Sharpens README and public-doc positioning for first-time visitors. | When a repo needs launch copy, clearer positioning, or a README that explains what the project is. |
| `oss-repo-readiness` | Audits and prepares a repo for open source release, focused on developer experience. | When making a repo public, writing CONTRIBUTING or issue templates, or running a pre-launch checklist. |
| `session-log-audit` | Mines local agent session logs for papercuts and produces a ranked fix list. | When the user wants to know what is annoying about their own tool, or why they work around it. |

## Notes

Expand All @@ -43,6 +44,10 @@ Actions self-hosted runners.
`docs/map/`. Its `docs` mode proposes doc and comment fixes on a separate
branch; source files change only in a comments-only commit, and nothing is
pushed without confirmation.
- Feature map records only drive steps it observed working, drives local or
development environments only, and writes into the generated `verify-<app>`
skill directory. The generated skill keeps entries current as agents verify
their changes.
- Whiteboard logs `suspected-bug` leads without investigating them; `verify-bug`
rules on them. Neither skill depends on the other.
- Bug verification never modifies the working tree. Repro tests run only in a
Expand Down
Loading
Loading