mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-19 15:36:29 +03:00
Magnus Hedemark
c5c4d2434a
Comprehensive open source contribution guidance with progressive disclosure. Restructured from a single ~23K-token monolithic SKILL.md into a concise ~1.2K-token orchestrator with 10 focused reference files. Changes: - SKILL.md: 1,720 lines → 100 lines (AgentSkills.io compliant frontmatter) - 10 new reference files covering phases 0a-4, pitfalls, default posture - Portable PR template compliance checker script (stdlib-only) - All personal context scrubbed for public export - AGENTS.md + README.md updated with trigger table entry Signed-off-by: Magnus Hedemark <magnus919@pm.me>
99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# Worked Example: Multi-PR Plan Execution Across Dependent Changes
|
|
|
|
## Context
|
|
|
|
A project needed two parallel feature tracks — backend model changes and browser automation — with a dependency chain of 8 issues spanning multiple microservices.
|
|
|
|
**Gaps discovered during testing:**
|
|
1. **No binary content support** — the scraper only produces markdown
|
|
2. **No Cloudflare bypass** — the browser service was trivially detectable as a bot
|
|
|
|
## Phase 0a: Contribution Infrastructure
|
|
|
|
Before filing any issues, set up `.github` templates and update CONTRIBUTING.md:
|
|
|
|
```
|
|
.github/
|
|
├── ISSUE_TEMPLATE/
|
|
│ ├── bug_report.md
|
|
│ └── feature_request.md
|
|
└── PULL_REQUEST_TEMPLATE.md
|
|
```
|
|
|
|
CONTRIBUTING.md updated with Conventional Commits + DCO sign-off + PR template reference.
|
|
|
|
## Phase 1: Ideation → Issues
|
|
|
|
Gaps were ideated into a dependency graph of 8 issues:
|
|
|
|
| # | Title | Track | Depends on |
|
|
|---|-------|-------|------------|
|
|
| #1 | Binary content response model | Gap 1 | — (foundation) |
|
|
| #2 | Stealth browser config | Gap 2 | — (foundation) |
|
|
| #3 | CLI download subcommand | Gap 1 | — (independent) |
|
|
| #4 | Content-type detection | Gap 1 | #1 |
|
|
| #5 | Cookie persistence | Gap 2 | #2 |
|
|
| #6 | Auto-recovery pipeline | Gap 1 | #4 |
|
|
| #7 | CAPTCHA-solving sidecar | Gap 2 | #2, #5 |
|
|
| #8 | Classification-based routing | Both | #6 |
|
|
|
|
Each issue body included a `## Dependencies` section:
|
|
- `**Requires:** #1 — cannot implement without this`
|
|
- `**Independent of:** #3 — separate scope`
|
|
|
|
### Key lesson: filing issues is the midpoint, not the finish line
|
|
|
|
After filing all issues, the next step is implementing the PRs. Filing issues documents the roadmap; implementing them delivers it.
|
|
|
|
## Phase 2: Multi-PR Execution
|
|
|
|
6 PRs were implemented following the dependency chain:
|
|
|
|
| PR # | Issue | Scope | Depends on |
|
|
|------|-------|-------|------------|
|
|
| A | #1 — Response model | API layer | — |
|
|
| B | #2 — Stealth browser | Browser service | — |
|
|
| C | Phase 0a — Templates | 4 config files | — |
|
|
| D | #3 — CLI download | CLI tool | — |
|
|
| E | #4 — Content detection | Scraper pipeline | A |
|
|
| F | #5 — Cookie persistence | Browser service | B |
|
|
|
|
### Execution pattern
|
|
|
|
Each PR followed the same workflow:
|
|
1. `git checkout main && git checkout -b feat/<descriptive-name>`
|
|
2. Implement changes
|
|
3. Verify syntax: `python3 -c "import ast; ast.parse(open('file').read())"`
|
|
4. `git add` + `git commit -s -m "type: description"`
|
|
5. `git push upstream HEAD`
|
|
6. `gh pr create --body-file /tmp/pr-body.md`
|
|
|
|
### Dependency handling
|
|
|
|
For dependent PRs (e.g., PR E depended on PR A's model changes):
|
|
- Branch was from main (not from the foundation branch)
|
|
- Code referenced new fields not yet on main
|
|
- PR body documented the dependency explicitly
|
|
- Foundation PRs submitted first — reviewer merges in order
|
|
- No branch stacking — each PR reviewable independently
|
|
|
|
## What Worked Well
|
|
|
|
- **Issue dependency metadata** made the roadmap navigable from any single issue
|
|
- **Foundation-first implementation** avoided merge conflicts
|
|
- **Consistent branch naming** (`feat/<feature>`) made relationships obvious
|
|
- **Syntax verification before commit** caught errors early
|
|
- **`--body-file` for PR creation** avoided shell escaping issues with special characters
|
|
|
|
## Common Pitfalls Encountered
|
|
|
|
- **File truncation during agent tool use**: Reading a file with a line-number-prefixed tool and writing it back can truncate content. Use direct Python file I/O (`open()`/`read()`/`write()`) for round-trips on large files.
|
|
- **Non-unique search patterns**: The patch tool failed on non-unique patterns in large files. Use precise surrounding context for reliable string matching.
|
|
|
|
## Key Metrics
|
|
|
|
- 12 distinct work items (4 infrastructure + 8 issues)
|
|
- 6 PRs submitted
|
|
- ~490 lines of code changed across 5 microservices
|
|
- Zero merge conflicts between dependent PRs
|