mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-12 20:16:29 +03:00
Magnus HedemarkandGitHub
1037324c2a
* feat: add programming-principles skill (14 classic software books) - SKILL.md v0.2.0 with cross-cutting principles, task-to-book mapping, and code-assessment workflow - 29 reference files (14 mini + 14 full + assessment methodology) - Agent-agnostic frontmatter (compatibility field, no Hermes-specific metadata) - Wire neckbeard routing table: code review/refactoring/quality assessment - Regenerate Claude marketplace + Codex plugin manifests (97 skills) Source: magnus919/programming-principles (standalone repo, v0.1.1). Local copy was v0.2.0 with code-assessment-workflow.md not yet upstreamed. Standalone repo will be archived with redirect after merge. * fix: satisfy validator — frontmatter fields, skill README, catalog entry - Strip version/author/source from frontmatter (unsupported fields) - Move source attribution into metadata (string-to-string map) - Add programming-principles/README.md with required headings - Add catalog entry to root README.md (alphabetical position) Validator passes locally: 107 canonical skills.
105 lines
4.4 KiB
Markdown
105 lines
4.4 KiB
Markdown
# Principles-Based Code Assessment Workflow
|
||
|
||
A reusable workflow for auditing a codebase (default branch + one open PR) against
|
||
programming-principles books and producing structured, deduplicated, prioritized findings.
|
||
|
||
## When to use
|
||
|
||
- User asks for a "code review", "code assessment", "architecture review", or
|
||
"code quality audit" referencing books like Clean Code, APoSD, WELC, Release It!, DDIA.
|
||
- User wants findings that go beyond surface lint — structural, design, reliability,
|
||
data-consistency, and architectural observations.
|
||
- The task involves a repo with existing issues and PRs that must be checked for overlap.
|
||
|
||
## Workflow
|
||
|
||
### 1. Load the evaluation frameworks
|
||
|
||
Load the relevant skills in parallel:
|
||
|
||
```markdown
|
||
skill_view(name='programming-principles')
|
||
skill_view(name='codebase-inspection')
|
||
```
|
||
|
||
The `programming-principles` skill provides the per-book rule catalogs
|
||
(Clean Code, APoSD, WELC, Release It!, DDIA) and cross-cutting principles.
|
||
The `codebase-inspection` skill provides the LOC metrics and the systematic
|
||
audit bug-class catalog.
|
||
|
||
### 2. Understand the codebase
|
||
|
||
- If the repo is local, use `find`/`git log`/`git branch -a` to map the tree.
|
||
- If remote, use `gh repo clone` or `web_extract`.
|
||
- Get a directory tree: `find <repo> -type f | grep -v '.git/' | head -100`.
|
||
- Read every source file. Read key ones first, but do not skip small files —
|
||
bugs cluster in overlooked files (configs, scripts, templates).
|
||
|
||
### 3. Read the GitHub context
|
||
|
||
This is critical for deduplication. Before writing findings:
|
||
|
||
- `gh pr view <N> --json title,body,files,additions,deletions,state` — for each
|
||
open PR. Understand what the PR changes and what it does not change.
|
||
- `gh issue list --state open --json number,title,body --limit 10` — list all
|
||
open issues. Read each one to understand what is already tracked.
|
||
- Cross-reference: a finding that overlaps an existing issue or PR is
|
||
**not** a new finding. Note the overlap and move on.
|
||
|
||
### 4. Apply the evaluation framework
|
||
|
||
For each finding, identify:
|
||
|
||
| Attribute | What |
|
||
|-----------|------|
|
||
| **File** | Exact path, line range |
|
||
| **Function/context** | Named function or logical block |
|
||
| **Book principle** | Which book(s) the finding violates. Use the task-to-book mapping from the programming-principles skill. |
|
||
| **Principle quote** | The specific rule from the book (e.g., "Functions should do one thing" — Clean Code) |
|
||
| **Impact** | Data loss, silent failure, incorrect behavior, maintainability drag |
|
||
| **Priority** | P1 (data loss/security/runtime failure), P2 (structural/maintainability), P3 (design concern, notification) |
|
||
| **Merits issue?** | Yes/No — an issue describes the problem and suggests a fix. Not everything needs an issue. |
|
||
| **Already covered?** | Check against open issues and PRs. If yes, exclude from the deliverable. |
|
||
|
||
### 5. Organize findings
|
||
|
||
Group by priority, then by book. Each finding should have:
|
||
|
||
```
|
||
### N. Title
|
||
**File:** `path/to/file.mjs`, lines X–Y
|
||
**Book:** Book Name (principle)
|
||
**Priority:** P1/P2/P3
|
||
|
||
Description of the problem, evidence from the code, and why it matters.
|
||
|
||
🟡 Merits issue #N: `tag: short description of fix`
|
||
```
|
||
|
||
### 6. Maintain an exclusion log
|
||
|
||
For things you explicitly chose not to flag, note why:
|
||
|
||
| Topic | Why excluded |
|
||
|-------|-------------|
|
||
| Missing X | Already covered by issue #N |
|
||
| Y pattern | Below actionable threshold for an audit |
|
||
|
||
This shows the reader you considered the space systematically.
|
||
|
||
## Common pitfalls
|
||
|
||
- **Don't stop after one file.** Read *every* source file — bugs hide in small scripts,
|
||
test helpers, and configuration templates.
|
||
- **Don't skip the PR branch.** The PR is the "planned implementation" the user asked
|
||
about. Read its new files from a worktree or diff to understand what changes.
|
||
- **Don't flag what's already tracked.** Reading issues and PRs first prevents wasted
|
||
effort and shows the user respect for their existing tracking.
|
||
- **Don't over-file.** A filing for every code smell produces noise. Issue findings when
|
||
the problem has real impact (data loss, security, structural friction that blocks
|
||
future changes). Minor things get a note but not an issue.
|
||
- **Don't forget to validate findings against both branches.** A finding may exist on
|
||
main but be fixed in the PR, or be introduced by the PR. Call out the delta.
|
||
- **Prefer exact line numbers.** Vague "file X has a problem" is not actionable.
|
||
Every finding needs exact file + function + line range.
|