Engineering-Specs/00-Index.md
Engineering Specs Index
Each spec is a superpowers:writing-plans-formatted document covering one cluster of the master plan (../00-Plan.md). Specs are independently executable by a fresh agent (Sonnet 4.6, teams mode): no agent needs to read the full 2000-line plan; they read their cluster spec.
Format reference: 01-foundations.md is the canonical exemplar. Every other spec follows its structure: Header → Goal/Architecture/Tech Stack → File Structure → SOP Rules → TDD Tasks → Acceptance Criteria → Out-of-Scope.
Cluster manifest
| # | Cluster | Master plan tasks | Depends on | Key modules |
|---|---|---|---|---|
| 01 | Foundations | 0, 1, 2, 6, 7 | : | DSS, types, session-store, blueprint-store |
| 02 | Sitemap discovery + URL streaming | 3, 4, +E (scope estimator) | 01 | sitemap.ts, path-grouper.ts, scope-estimator.ts |
| 03 | WAF detection + page sampling | 8, +B (WAF + Playwright) | 01 | waf-detector.ts, playwright-fetcher.ts, sampler.ts |
| 04 | CMS detection + content classification | 5, +A (CMS detector), +C (site-type rubric) | 01, 03 | cms-detector.ts, classifier.ts, site-type-rubric.ts |
| 05 | Structure analysis + extractor + sandbox + canonical | 9, 10, 11, +D (canonical inferer) | 01, 03, 04 | structure-analyzer.ts, extractor-generator.ts, record-extractor-template.ts, sandbox-runner.ts, canonical-inferer.ts |
| 06 | Crawler API client + index manager | 12, 13 | 01 | crawler-client.ts, index-manager.ts |
| 07 | Brand domain discovery | +F (brand-domain discoverer) | 03 | brand-domain-discoverer.ts |
| 08 | Backend API endpoints | 14–21 | 01–07 | api-src/factory/{discover, sample, generate-extractor, test-sandbox, test-real, create-crawler, crawl-progress, session, blueprints}.ts |
| 09 | Frontend foundations | 22, 23 | 08 | App.tsx, AdminFactory.tsx, hooks/factory/* |
| 10 | Frontend discovery flow | 24, 25, 26 | 09 | RollingLog, DomainBadge, DiscoveryPanel, CategoryReview |
| 11 | Frontend configurator | 27 | 10 | CategoryConfigurator, SamplePreview, ConfigEditor, TestCrawlResults |
| 12 | Frontend live monitor + orchestrator | 28, 29 | 11 | LiveCrawlMonitor, CrawlerFactory orchestrator |
| 13 | Bundle + smoke + docs + vault sync | 30, 31 | All | bundle outputs, docs/factory/README.md, Status.md updates |
Build order: 01 → 02, 03, 06, 07 (parallel after 01) → 04 (after 03) → 05 (after 04) → 08 (after 05, 06, 07) → 09 → 10 → 11 → 12 → 13.
Parallelism opportunities: clusters 02/03/06/07 can run in parallel after 01. Frontend clusters 10/11 can be worked sequentially or in parallel after 09 with careful coordination of shared factory/ component imports.
Format contract (every spec MUST contain)
- Header: exact format from writing-plans skill (Goal, Architecture, Tech Stack, depends-on)
- File structure table: every file with its responsibility
- SOP rules section: applied CodingSOPs/TestingSOPs/WritingSOPs rules verbatim (try/catch, logger, zod, function ≤20 lines, no
any, etc.) - TDD tasks: bite-sized 2-5 minute steps with full code; test first → run/fail → implement → run/pass → commit
- No placeholders: every step has the actual code an engineer needs (per writing-plans rule)
- Acceptance criteria: checkboxed list defining "done"
- Out of scope: what this spec doesn't do, plus pointer to which spec does
Why per-cluster specs (vs. one giant spec)
- Parallelizable execution. 12 agents (Sonnet 4.6, teams mode) can pick up specs 02–13 simultaneously after 01 lands.
- Bounded context. Each agent's working memory is ~700 lines, not 2000. Better focus, fewer mistakes.
- Independent review. A reviewer can sign off on a spec without re-deriving the whole architecture.
- Localized failure. A test failure in spec 04 doesn't block spec 06 from progressing.
The master plan (00-Plan.md) remains the architectural truth; specs are its executable shadow.