@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/docs/product/prd-contract.md

@@ -0,0 +1,107 @@
+---
+description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
+---
+
+# Product PRD Contract
+
+Load this module immediately before writing or updating any PRD.
+
+## Output paths
+
+- Creation / enrichment mode → `.aioson/context/prd.md`
+- Feature mode → `.aioson/context/prd-{slug}.md`
+
+`.aioson/context/` accepts only `.md` files.
+
+## Required PRD structure
+
+Use exactly these sections:
+
+```markdown
+# PRD — [Project Name]
+
+## Vision
+[One sentence. What this product is and why it matters.]
+
+## Problem
+[2–3 lines. The specific pain point and who experiences it.]
+
+## Users
+- [Role]: [what they need to accomplish]
+- [Role]: [what they need to accomplish]
+
+## MVP scope
+### Must-have 🔴
+- [Feature or capability — why it's required for launch]
+
+### Should-have 🟡
+- [Feature or capability — why it's valuable but not blocking]
+
+## Out of scope
+- [What is explicitly excluded from this version]
+
+## User flows
+### [Key flow name]
+[Step-by-step: User does X → System does Y → User sees Z]
+
+## Success metrics
+- [Metric]: [target and timeframe]
+
+## Open questions
+- [Unresolved decision that needs an answer before or during development]
+
+## Visual identity
+### Design skill
+### Aesthetic direction
+### Color & theme
+### Typography
+### Motion & interactions
+### Component style
+### Quality bar
+```
+
+## Visual identity inclusion rule
+
+Include `## Visual identity` when:
+
+- the client expressed visual preferences, or
+- `design_skill` is already set in `project.context.md`
+
+Omit it only when visual requirements were truly not discussed and no design skill was selected.
+
+### Design skill block
+
+Inside `### Design skill`:
+
+- write the selected design skill if chosen
+- if postponed, write `pending-selection`
+- add a note that `@ux-ui` must read `.aioson/skills/design/{skill}/SKILL.md` before design work when a skill is selected
+
+## Writing rules
+
+- Do not invent undiscussed content unless the user explicitly requested surprise mode
+- In standard finalize mode, unresolved sections become `TBD — not discussed.`
+- Keep the PRD focused; summarize sections that are getting too long
+- Preserve the user's product framing; do not drift into analyst or architect territory
+
+## Next-step routing
+
+After the PRD is produced:
+
+### New project (`prd.md`)
+
+| classification | Next step |
+|---|---|
+| MICRO | `@dev` |
+| SMALL | `@analyst` |
+| MEDIUM | `@analyst` then `@architect` → `@ux-ui` → `@pm` → `@orchestrator` |
+
+### New feature (`prd-{slug}.md`)
+
+| feature complexity | Next step |
+|---|---|
+| MICRO | `@dev` |
+| SMALL | `@analyst` |
+| MEDIUM | `@analyst` → `@architect` → `@dev` → `@qa` |
+
+Assess feature complexity from the conversation and state the next agent explicitly.

package/template/.aioson/docs/product/quality-lens.md

@@ -0,0 +1,57 @@
+---
+description: "Product quality lens — strong patterns, anti-pattern replacements, and a compact scorecard for higher-quality PRDs."
+---
+
+# Product Quality Lens
+
+Load this module before writing or updating any PRD.
+
+## Positive patterns
+
+High-quality product output usually does all of this:
+
+- names a specific user and a specific pain instead of a generic audience
+- shows the tension behind the first release: what matters now and what is deliberately deferred
+- captures edge cases, empty states, permissions, and failure behavior early
+- explains why this product should be chosen instead of a generic alternative
+- leaves downstream agents with decisions they can execute, not vague aspirations
+- preserves visual ambition when visual quality changes the product outcome
+
+## Anti-patterns and replacements
+
+| Anti-pattern | Replace with |
+|---|---|
+| Generic SaaS PRD that could fit any startup | A PRD with domain nouns, real user moments, and explicit constraints |
+| Feature list without decision tension | A scoped first release with clear deferrals |
+| User story with no operator or owner | Named roles, ownership, and state transitions |
+| Competitive claim with no evidence | Research-backed differentiation or explicit uncertainty |
+| Beautiful-product language with no design bar | A concrete `## Visual identity` direction or `pending-selection` |
+
+## Elevation moves
+
+Before finalizing, force at least one improvement from each category:
+
+- sharpen the user/problem statement
+- sharpen the scope boundary
+- sharpen one risk or edge case
+- sharpen one differentiator or positioning detail
+
+## Review scorecard
+
+Score the PRD from `1-5` on:
+
+- specificity
+- differentiation
+- scope discipline
+- downstream usefulness
+- operational realism
+
+If any score is `3` or lower, revise before finalizing.
+
+## Final pass
+
+Ask silently:
+
+- Would this still read as strong if the product name were removed?
+- Does at least one section prove the product is not a template clone?
+- Can `@analyst`, `@ux-ui`, and `@dev` act on this without guessing core intent?

package/template/.aioson/docs/product/research-loop.md

@@ -0,0 +1,65 @@
+---
+description: "Product research loop — extract short keyword phrases, consult research cache, search fresh sources, and fold the findings back into the PRD conversation."
+---
+
+# Product Research Loop
+
+Load this module before the first synthesis, before any finalize decision, and before writing a non-trivial PRD.
+
+## Goal
+
+Prevent `@product` from relying only on the chat. Use a lightweight, fresh external evidence pass to sharpen questions, differentiate the PRD, and avoid generic product output.
+
+## Mandatory keyword extraction
+
+Derive `3-7` short keyword phrases from the current conversation. Favor concrete phrases with `2-6` words such as:
+
+- problem or pain point
+- user segment or buyer
+- workflow or operating motion
+- business model or pricing shape
+- trust, compliance, or risk concern
+- differentiation claim
+- visual or experience cue when it changes the product
+
+Good phrases are specific and searchable:
+
+- `ai intake form`
+- `b2b onboarding checklist`
+- `field service scheduling`
+- `subscription upgrade friction`
+
+Avoid broad phrases such as `app idea`, `dashboard`, or `better ux`.
+
+## Mandatory scouting pass
+
+1. Load `.aioson/skills/static/web-research-cache.md`
+2. Rank the extracted phrases by:
+   - freshness sensitivity
+   - product impact
+   - likelihood of improving the PRD
+3. Check the cache first for the top phrases
+4. Reuse fresh cache entries when they are less than 7 days old
+5. Search only the top `1-4` phrases that are stale or missing
+6. Save every search to `researchs/` before using the result
+
+At least one phrase must be validated through cache or fresh research whenever the PRD depends on an external market, product pattern, pricing model, competitor norm, compliance expectation, or time-sensitive UX convention.
+
+## How to use the findings
+
+Use research to:
+
+- ask sharper follow-up questions
+- surface missing constraints or edge cases
+- challenge commodity positioning
+- strengthen differentiation and first-release scope
+- improve acceptance of what should stay `TBD`
+
+Do not dump research into the chat. Surface only the deltas that materially change the product conversation.
+
+## Output discipline
+
+- Treat `researchs/` as a temporary shared evidence layer for current and nearby sessions
+- Mark inferred conclusions as inference, not as sourced fact
+- Never replace user confirmation with internet research
+- Never force a PRD rewrite because research exists; use it to improve judgment and questions

package/template/.aioson/docs/sheldon/enrichment-paths.md

@@ -0,0 +1,134 @@
+---
+description: "Sheldon enrichment paths — gap analysis dimensions, sizing, in-place vs phased plan outputs, enrichment log, and handoff."
+---
+
+# Sheldon Enrichment Paths
+
+Load this module after source consolidation and before writing any enrichment output.
+
+## Gap analysis dimensions
+
+Analyze the PRD for:
+
+- missing requirements
+- edge cases
+- vague or absent acceptance criteria
+- unresolved technical decisions
+- unmapped external dependencies
+- incomplete user flows
+- internal contradictions
+
+Show improvements grouped by:
+
+- critical gaps
+- important improvements
+- refinements
+
+The user must choose which improvements to apply before you write anything.
+
+## Sizing decision
+
+Score the enriched scope using:
+
+| Criterion | Weight |
+|---|---|
+| Main entities above 3 | +1 each |
+| Distinct delivery phases above 1 | +2 each |
+| External integrations | +1 each |
+| User flows above 3 | +1 each |
+| AC complexity above 10 | +1 |
+
+Decision thresholds:
+
+- `0–3` → enrich PRD in place
+- `4–6` → enrich PRD in place and add `## Delivery plan`
+- `7+` → create external phased plan in `.aioson/plans/{slug}/`
+
+Present the decision and justification before creating any files.
+
+## Path A — In-place enrichment
+
+For scores `0–6`:
+
+- expand existing sections
+- add missing sections when needed
+- never remove existing content
+- never rewrite `Vision`, `Problem`, or `Users`
+- mark Sheldon-added content with `_(sheldon)_`
+
+For scores `4–6`, add `## Delivery plan` with numbered phases inside the PRD.
+
+Also add or update:
+
+- `## Reference sources (sheldon)`
+
+## Path B — External phased plan
+
+For scores `7+`, create:
+
+- `.aioson/plans/{slug}/manifest.md`
+- `.aioson/plans/{slug}/plan-{phase-slug}.md`
+
+Rules:
+
+- create `manifest.md` first
+- phase slugs must be descriptive
+- phases must be independently implementable
+- phase ACs must be independently verifiable
+- pre-made decisions are final
+- deferred decisions must state who decides and when
+
+## `manifest.md`
+
+Include:
+
+- target PRD
+- Sheldon version
+- created date
+- status
+- overview
+- phase table
+- pre-made decisions
+- deferred decisions
+- reference sources
+
+## `plan-{phase-slug}.md`
+
+Each phase file should include:
+
+- scope
+- new or modified entities
+- user flows covered
+- acceptance criteria
+- implementation sequence
+- external dependencies
+- notes for `@dev`
+- notes for `@qa`
+- phase-specific reference sources
+
+## Enrichment log
+
+Create or update `.aioson/context/sheldon-enrichment.md` at the end of every session.
+
+It must track:
+
+- target PRD
+- enrichment round count
+- last enrichment date
+- plan path or `null`
+- sizing score
+- sizing decision
+- sources used
+- improvements applied
+- improvements discarded
+
+## Handoff
+
+If enrichment stayed in-place:
+
+- tell the user to activate `@analyst`
+
+If an external phased plan was created:
+
+- tell the user where `manifest.md` lives
+- tell them to activate `@analyst`

package/template/.aioson/docs/sheldon/harness-contract.md

@@ -0,0 +1,118 @@
+---
+description: "Sheldon harness contract generation procedure — schemas, criteria population, governor and contract_mode selection, MICRO/SMALL/MEDIUM rules."
+---
+
+# Sheldon Harness Contract Generation
+
+Load this module when `@sheldon` reaches RF-05 in a MEDIUM enrichment. Implements AC-HD-06 of `harness-driven-aioson`.
+
+## When to run
+
+Run **after** writing `sheldon-enrichment-{slug}.md`, gated by `project.context.md` classification:
+
+| Classification | Action |
+|---|---|
+| MICRO | Skip entirely. No contract, no progress.json. |
+| SMALL | Produce `progress.json` only (no `harness-contract.json`). |
+| MEDIUM | Produce both `harness-contract.json` and `progress.json`. |
+
+## Steps
+
+### 1. Initialize stub
+
+If `.aioson/plans/{slug}/harness-contract.json` is absent:
+
+```bash
+aioson harness:init . --slug={slug}
+```
+
+This creates the contract scaffold and `progress.json` in the same folder. If the CLI command is unavailable, write both files manually using the canonical schemas at the bottom of this doc.
+
+### 2. Populate `criteria[]`
+
+For every AC in the enriched PRD with an objective, mechanically verifiable assertion (file existence, test pass, lint clean, exact API shape, exit code), append to `criteria[]`:
+
+```json
+{
+  "id": "C1",
+  "description": "<AC text — human-readable for PR review>",
+  "assertion": "<machine-verifiable expression — e.g. 'tests/foo.test.js passes' or 'src/x/y.js exports parseX'>",
+  "binary": true
+}
+```
+
+ACs that are subjective (UX feel, code style preference) get `binary: false` and become advisory only — `@validator` ignores them in the score.
+
+**Rule of thumb:** if the assertion can be answered by a single shell command exit code or a single test, it qualifies as `binary: true`. Otherwise mark it advisory and let `@qa` cover it.
+
+### 3. Set `contract_mode`
+
+By classification and risk surface:
+
+- **SMALL** → `ECONOMICAL` (relaxed governor)
+- **MEDIUM (default)** → `BALANCED`
+- **MEDIUM with sensitive surface** (auth, money, ownership, secrets, uploads, external URLs) → `URGENT` (tight governor)
+
+### 4. Set `governor` block
+
+Safe defaults for `BALANCED`:
+
+```json
+{ "max_steps": 50, "cost_ceiling_usd": 2.00, "error_streak_limit": 5 }
+```
+
+- `URGENT` halves these.
+- `ECONOMICAL` doubles `error_streak_limit` only.
+
+## Authoring rules
+
+- The contract is **additive** to the enrichment log; both coexist. Enrichment explains *what* to enrich; contract defines *what "done" means*.
+- Contract criteria are derived from the **enriched** PRD ACs — never invent criteria not anchored to an AC.
+- Mention the contract path in the post-enrichment handoff message.
+- The user approves the contract as part of the post-enrichment gate. Do not declare the contract final without confirmation.
+- Once approved, the contract is the source of truth for `@validator`. Subsequent enrichment rounds may add new criteria, never remove approved ones without explicit user instruction.
+
+## Canonical schemas
+
+### `harness-contract.json`
+
+```json
+{
+  "feature": "<slug>",
+  "contract_mode": "ECONOMICAL | BALANCED | URGENT",
+  "governor": {
+    "max_steps": 50,
+    "cost_ceiling_usd": 2.00,
+    "error_streak_limit": 5
+  },
+  "criteria": [
+    {
+      "id": "C1",
+      "description": "...",
+      "assertion": "...",
+      "binary": true
+    }
+  ]
+}
+```
+
+### `progress.json`
+
+```json
+{
+  "feature": "<slug>",
+  "phase": 1,
+  "status": "in_progress | waiting_validation | done | circuit_open",
+  "completed_steps": [],
+  "last_error": null,
+  "session_count": 1,
+  "last_updated": "<ISO-8601>",
+  "circuit_state": "CLOSED | OPEN | HALF_OPEN"
+}
+```
+
+## Failure modes to anticipate
+
+- **No verifiable ACs in PRD** — go back to enrichment with `@product` and add concrete assertions before generating a contract.
+- **All ACs are advisory** — flag to user; the harness adds no value. Skip contract generation, document the decision in `sheldon-enrichment-{slug}.md`.
+- **`harness:init` CLI missing** — write stubs manually, but record in handoff that CLI was unavailable so `@dev` can install it.

package/template/.aioson/docs/sheldon/quality-lens.md

@@ -0,0 +1,57 @@
+---
+description: "Sheldon quality lens — high-signal enrichment patterns, anti-pattern replacements, and a compact review rubric."
+---
+
+# Sheldon Quality Lens
+
+Load this module before presenting improvements, sizing, or phased planning.
+
+## Positive patterns
+
+High-quality Sheldon output usually does all of this:
+
+- isolates the few gaps that would actually break downstream work
+- distinguishes product gaps, technical gaps, and execution gaps
+- ranks recommendations by severity and evidence, not by verbosity
+- preserves `@product` ownership of vision, users, and problem framing
+- uses fresh validation when technology or domain assumptions may have aged
+- recommends a phased plan only when complexity or risk justifies it
+
+## Anti-patterns and replacements
+
+| Anti-pattern | Replace with |
+|---|---|
+| Rewriting the PRD with different words | Referencing sections and proposing targeted deltas |
+| Long lists of equal-priority suggestions | A short, ordered set of critical improvements |
+| Technical speculation without evidence | Evidence-backed validation or explicit uncertainty |
+| Cosmetic refinements presented as blockers | Clear separation between critical and optional changes |
+| Phase plan created by reflex | A justified decision tied to scope, dependencies, or risk |
+
+## Elevation moves
+
+Before finalizing, strengthen at least one item in each area:
+
+- evidence quality
+- severity ordering
+- downstream actionability
+- freshness validation
+
+## Review scorecard
+
+Score from `1-5` on:
+
+- criticality
+- evidence strength
+- prioritization clarity
+- downstream usefulness
+- execution realism
+
+If any score is `3` or lower, tighten the output before presenting it.
+
+## Final pass
+
+Ask silently:
+
+- Would `@dev` or `@qa` materially avoid rework because of this enrichment?
+- Did I separate confirmed issues from optional upgrades?
+- If I proposed a phased plan, is the reason strong enough to defend?

package/template/.aioson/docs/sheldon/research-loop.md

@@ -0,0 +1,56 @@
+---
+description: "Sheldon research loop — extract short keyword phrases from the PRD and sources, consult research cache, and use fresh findings to prioritize enrichment."
+---
+
+# Sheldon Research Loop
+
+Load this module after source consolidation and before sizing.
+
+## Goal
+
+Give `@sheldon` a lightweight but mandatory fresh-research pass so enrichment decisions are not limited to the PRD text or the user-supplied sources.
+
+## Mandatory keyword extraction
+
+Derive `3-7` short keyword phrases from:
+
+- the PRD's riskiest assumptions
+- unresolved flows or business rules
+- integrations, vendors, or external systems
+- domain nouns that affect quality
+- differentiators or market claims
+- technical patterns that may have aged
+
+Keep phrases short, concrete, and searchable. Prefer `2-6` words.
+
+## Mandatory scouting pass
+
+1. Load `.aioson/skills/static/web-research-cache.md`
+2. Rank phrases by:
+   - staleness risk
+   - chance of changing the PRD or phase plan
+   - risk to downstream implementation
+3. Reuse fresh `researchs/` hits first
+4. Search only the top `1-4` stale or missing phrases
+5. Save every result before using it
+
+At least one phrase must be validated through cache or fresh research whenever the PRD touches an external market, evolving UI pattern, vendor dependency, compliance surface, or non-trivial technical choice.
+
+## How to use the findings
+
+Use research to:
+
+- reprioritize improvements
+- distinguish critical gaps from cosmetic refinements
+- justify whether phased planning is necessary
+- challenge stale technical or product assumptions
+- enrich edge cases and operational details
+
+If the research is purely technical and tied to named stack decisions, combine this module with `.aioson/docs/sheldon/web-intelligence.md`.
+
+## Output discipline
+
+- `researchs/` is a temporary shared evidence layer, not a substitute for the PRD
+- show only findings that change priority, sizing, or correctness
+- mark inference separately from sourced facts
+- do not force enrichment changes without user confirmation

package/template/.aioson/docs/sheldon/web-intelligence.md

@@ -0,0 +1,75 @@
+---
+description: "Sheldon web intelligence protocol — stale-tech validation, research cache, verdicts, and output rules."
+---
+
+# Sheldon Web Intelligence
+
+Load this module when the target PRD names technologies, frameworks, integrations, or technical patterns that may be stale.
+
+## Goal
+
+Validate whether the technical decisions mentioned in the PRD are still good choices as of today.
+
+## When to run
+
+Run after source consolidation and before sizing.
+If the PRD contains no specific technical decisions, skip silently.
+
+## Technical signals to extract
+
+Look for:
+
+- named technologies or frameworks
+- architectural patterns
+- external integrations
+- stack decisions
+
+## Search protocol
+
+For each high-risk technical signal:
+
+1. Check `researchs/{decision-slug}/summary.md`
+2. If a result exists and is less than 7 days old, reuse it
+3. Otherwise search using the current year
+4. Classify the result as:
+   - `confirmed`
+   - `has-alternatives`
+   - `outdated`
+   - `deprecated`
+
+Max 4 searches per session.
+
+## Save to `researchs/`
+
+For each search, create:
+
+- `researchs/{decision-slug}/summary.md`
+- raw consulted pages under `researchs/{decision-slug}/files/`
+
+`summary.md` frontmatter must include:
+
+- `searched_at`
+- `agent: sheldon`
+- `prd`
+- `query`
+- `verdict`
+
+## User-facing output rule
+
+Show only actionable findings:
+
+- `has-alternatives`
+- `outdated`
+- `deprecated`
+
+If every finding is `confirmed`, tell the user no update is needed.
+
+Never silently modify the PRD based on web validation.
+Ask whether to incorporate the update first.
+
+## Failure behavior
+
+If a search fails:
+
+- log the failure in `summary.md`
+- continue without blocking the session