| name | athenai-plan |
| description | Phase 1-2 of athenai-implement pipeline — produce plan.md with authored HTML structure, parsing logic, and tasks section. Includes draft test content generation with mandatory edge case coverage. |
Athenai Plan — Phases 1-2
Phase 1 — Plan
Goal: Produce plan.md (with Authored HTML Structure, Parsing Logic, and Tasks section for Simple/Standard blocks).
Collapsed Research (Fast Mode)
Skip block-collection-and-party and docs-search unless the block type is completely unrecognised (no existing block in blocks/ directory matches the feature). If skipping, note "research skipped in fast mode" in report.
Load Context
- Required:
spec.md, .specify/memory/constitution.md
- If exists:
design.md (source of truth for HTML/CSS — overrides prose in spec)
- Load
IMPL_PLAN template from .specify/scripts/bash/setup-plan.sh --json
Produce Artifacts
-
plan.md: Architecture decisions, tech stack, file list, block name, variants, implementation approach. Reference design.md Code Scaffold and Layout matrix where applicable. Include these additional sections at the bottom of the file (in this order):
## Authored HTML Structure — The actual <div> nesting EDS produces from the authored block table, before decorate() runs. Cover the full-field example (all rows populated). This replaces the former data-model.md's unique content and gives the implementer a concrete DOM starting point.
## Parsing Logic — Pseudocode for the decorate() iteration pattern: how to extract the key from children[0], access value cells from remaining children, and match keys case-insensitively.
## Tasks — For Simple and Standard complexity blocks (see Complexity Classification below), generate the full Tasks section inline during Phase 1 using the Required Tasks list and Phase Structure. This eliminates Phase 2 as a separate step, saving ~50 seconds of phase overhead + inter-phase gap. For Complex blocks (9+ tasks, multiple blocks, cross-block dependencies), leave the Tasks section as a stub heading and let Phase 2 fill it separately.
To determine complexity: count the number of user stories, check if the feature spans multiple blocks, and check for third-party integrations. A single new block with variants is Standard; only escalate to Complex when justified.
Do not generate data-model.md or quickstart.md — the data model is already covered by spec.md's Content Model section, and quickstart content is fully derivable from spec.md + design.md.
Draft Test Content (CDD Phase 1.3)
Skip guard: If drafts/{blockname}.plain.html already exists (pre-generated by the draft-content-generator background subagent launched during input validation), skip this entire subsection. Note "draft content pre-generated by background agent" in the Phase 1 report and proceed to Block Scaffolding. The file will be validated in Phase 5.
Generate draft HTML test content in drafts/{blockname}.plain.html based on spec.md's Content Model section and the ## Authored HTML Structure section in plan.md. File must:
- Use
.plain.html extension
- Contain only section content (
<div> wrappers with block tables and default content)
- MUST NOT include
<!DOCTYPE html>, <html>, <head>, <body>, <header>, <main>, or <footer> tags — the AEM dev server wraps .plain.html content with the full page shell automatically (scripts.js, styles.css, header/footer blocks). Including these tags breaks the decoration pipeline and prevents block JS and CSS from loading. The file must start directly with <div> or <hr> section elements.
- Section / block DOM (MANDATORY — do not skip):
decorateSections in scripts/aem.js treats each direct child div of main as one section. decorateBlocks only decorates elements matching main > div.section > div > div (the block is the inner div, first class = block name). Therefore div.{blockName} must never be a direct child of main alongside other top-level section divs — if it is, that element becomes the section root, the block’s inner rows are split into separate wrappers, and the block module never loads. Always wrap the entire draft in a single outer <div>...</div> (all <hr> breaks, headings, and div.{blockName} blocks live inside it) unless you intentionally mirror production with one wrapper per section so each block is nested section > wrapper > div.{blockName}. When in doubt, use one outer wrapper for the whole file.
- Cover all block variants from the spec
- Cover edge cases from spec.md — every item listed in the Edge Cases section MUST have a corresponding section in the draft HTML. At minimum include variants for: invalid/unparseable inputs, boundary conditions (e.g. past dates, empty optional fields), and any graceful-degradation scenario the spec describes. These are critical for verifying that
decorate() handles bad data without breaking the page.
Edge Case Sourcing (MANDATORY)
STOP — Edge cases are REQUIRED in draft test content.
Check these sources in order and ensure draft HTML includes variants for each scenario:
-
testcases.csv — if FEATURE_DIR/testcases.csv exists (from a prior run or manual creation), scan it for test cases whose Title contains "edge", "invalid", "error", "missing", "empty", "boundary", "fallback", or "graceful". Extract the scenario described in each matching test case and ensure the draft HTML includes a variant that exercises it.
-
spec.md Edge Cases section — always read this section and generate a draft variant for every bullet point. This is the primary source even when testcases.csv exists, because the CSV may not cover all spec-level edge cases.
-
Implicit edge cases — if the Content Model has required fields, include at least one variant where a required field contains an obviously invalid value (to verify graceful degradation), and one variant where all optional fields are omitted (minimal configuration).
Verification gate: Before proceeding, confirm that the draft HTML file contains sections for:
- At least one invalid/unparseable input scenario
- At least one boundary condition scenario
- At least one graceful degradation scenario (if applicable to this block)
If any are missing, add them now. Do not proceed without edge case variants.
Block Scaffolding in Phase 1 (SC001)
Create the block directory during Phase 1 alongside draft test content creation: mkdir -p blocks/{blockname}. This is a filesystem setup step with no dependency on the Tasks section — it only needs the block name, which is known from spec.md. Moving SC001 here allows Phase 3 to begin writing JS/CSS immediately without a scaffold-then-verify step.
Timer
start 1-plan on the main log (after Phase 0 decision and any Phase 0 work) — or chained from Phase 0 end. When Phase 1 completes, chain the transition to the next phase in a single shell call (e.g. end 1-plan && start 3-implement when Phase 2 is inlined, or end 1-plan && start 2-tasks when Phase 2 runs separately).
Background Figma asset job: If Phase 0 launched a background asset download job (curl / sips / optional subagent), it may still be running during Phase 1 — that is intentional. Phase 1 must not wait for those files; only Phase 3 awaits completion.
Print Phase 1 report after starting the next timer.
Phase 2 — Tasks (Complex blocks only)
Goal: Fill the ## Tasks section in plan.md.
Guard: If Phase 1 already generated the Tasks section inline (Simple/Standard complexity), skip Phase 2 entirely. Print:
## ✓ Phase 2 — Tasks inlined in Phase 1
- **Outputs**: Tasks section already in plan.md (generated during Phase 1)
- **Key decisions**: Simple/Standard complexity — Phase 2 merged into Phase 1
- **Next**: Phase 3 — Implement
Do not record 2-tasks timer events when inlined. Proceed directly to Phase 3.
Phase 2 only runs as a separate step for Complex blocks (9+ tasks, multiple blocks, cross-block dependencies) where the task decomposition requires dedicated reasoning.
Load Context
- Required:
plan.md (contains Tasks stub, Authored HTML Structure, Parsing Logic), spec.md, draft test content
- If exists:
design.md
- Load
.specify/templates/tasks-template.md for structure
Tasks are written into the ## Tasks section of plan.md, not a new file.
Complexity Classification
| Class | Task count | Criteria |
|---|
| Simple | 2–4 | CSS-only, minor JS fix, single-file |
| Standard | 5–8 | New block (JS + CSS), variants |
| Complex | 9–15 | Multiple blocks, third-party, cross-block |
Task Format
- [ ] [Category-ID] [P] Description with file path
Categories: BJ (Block JS), BC (Block CSS), CS (Core Scripts), GS (Global Styles), CT (Content), IN (Integration), TS (Testing), DC (Documentation), T (Setup), SC (Scaffolding).
Required Tasks (Always Generate)
SC001 — Block scaffolding (create blocks/{name}/{name}.js and {name}.css)BJ001 — Block JS decorationBC001 — Block CSS (mobile-first file order; Layout matrix compliance when design.md exists)T001 — Test content verification (.plain.html format, structure validation, all variants and edge cases covered)TS001 — ESLint (npm run lint)TS002 — Stylelint (npm run lint)CT001 — Content validation (verify draft HTML covers all implemented variants; visual check is manual — see Recommended Next Steps in Phase 5)
Omit in Demo Mode
TS006 (unit tests) — always omitTS004 (PSI check) — omitDC* (documentation tasks) — omit
Phase Structure
- Phase 1: Setup — T001 (test content gate), SC001
- Phase 2: Foundation — core script changes if needed
- Phase 3.X: User Stories — one sub-phase per user story
- Final Phase: QA — TS001, TS002, CT001
When design.md exists: BJ001 produces HTML matching design.md Code Scaffold; BC001 implements design.md CSS Skeleton in mobile-first file order.
Timer
start/end 2-tasks on the log for the agent that runs this phase: subagent A log in parallel mode, or main log if --no-parallel. When Phase 2 completes, chain end 2-tasks && start 3-implement in a single shell call.
Print Phase 2 report after starting the Phase 3 timer. Output is plan.md (Tasks section updated), not a separate tasks.md.
