The foundational template for creating new Longshot projects with all required documentation
The basic project template (examples/example/) provides the starting point for all Longshot projects. It includes all required specification and operational documents with placeholders and guidance.
The authoritative source for product requirements, success criteria, and scope.Key Sections:
## Product Statement2-4 sentences: what you are building, for whom, and the primary use case## Success Criteria (Ranked)1. Highest-priority outcome with measurable target2. Second-priority outcome with measurable target 3. Third-priority outcome with measurable target### Hard Limits- Time budget: e.g. 8 hours- Resource budget: e.g. <= 2 CPU cores, <= 2 GB RAM- External services: e.g. no paid APIs- Runtime mode: e.g. must run offline## Acceptance Tests (Runnable, Objective)- `exact command` results in `exact expected output/behavior`- `manual flow with clear pass condition`## Scope Model### Must Have (3-7)- Capability spine items### Nice to Have (3-7) - Optional enhancements### Out of Scope- Tempting but intentionally excluded items
Document Ownership:
Type: User input to swarm
Created by: User before run
Updated by: User is primary editor; agents propose edits but cannot change intent without approval
Defines how agents should execute work in the repository.Key Sections:
## Scope Discipline- Derive tasks from SPEC.md boundaries and acceptance tests- Prefer small, merge-safe changes## Code Style - Follow existing naming and patterns- Avoid placeholders and TODO stubs- Keep functions small with explicit types## Dependencies- Allowed: list allowed runtime/test deps- Banned: dependencies not allowed without approval## Testing Policy- Run targeted tests before completion- Run all acceptance tests before handoff- Never delete tests to hide failures## Commit Expectations- Focused commits mapping to acceptance tests- Message format: e.g. feat(scope): summary
Document Ownership:
Type: User input to swarm
Created by: User before run
Updated by: User primarily; agents propose updates when constraints unclear
Fill all sections with specific requirements. Remove all placeholder text (<...>). Ensure acceptance tests are runnable commands with exact expected outputs.
2
Complete AGENTS.md
Define concrete policies for dependencies, testing, commits, and code style. No vague guidelines - make them enforceable.
3
Bootstrap README.md
Write exact setup commands that work from a clean machine. Test them yourself before running swarm.
4
Bootstrap RUNBOOK.md
Define initial operating modes and monitoring approach. Agents will expand this during execution.
5
Initialize DECISIONS.md
Add at least one initial architecture decision if you’ve made technology choices.
6
Verify ENTRY_POINT.md
Confirm the ownership matrix matches your project policy.
## Product StatementA command-line web scraper that monitors product prices across multiple e-commerce sites. Users provide URLs via a config file, the scraper runs on a schedule, and price history is stored in SQLite for analysis and alerts.## Success Criteria (Ranked) 1. Successfully scrape and store prices from 3 target sites (Amazon, eBay, Walmart) with 95%+ success rate2. Detect price changes and log alerts when drops exceed 10%3. Complete scrape cycle for 100 products in under 5 minutes### Hard Limits- Time budget: 8 hours- Resource budget: <= 1 CPU core, <= 512 MB RAM- External services: No paid APIs (free proxy rotation acceptable)- Runtime mode: Must run offline after initial install## Acceptance Tests- `npm start -- --config test-urls.json` completes with exit code 0- `sqlite3 prices.db "SELECT COUNT(*) FROM price_history"` returns > 0 - Manually verify: scrape Amazon product, change price in test mock, re-scrape, confirm new price recorded
## Dependencies- Allowed: `puppeteer`, `cheerio`, `better-sqlite3`, `node-cron`, `zod`- Banned: Paid services, Playwright (Puppeteer sufficient), heavy ORMs (use raw SQL with sqlite3)## Testing Policy - Every scraper module has unit test with mocked HTTP responses- Run `npm test` before every commit- Run full acceptance test suite before handoff