@jaimevalasek/aioson 1.5.1 → 1.7.0

package/template/.aioson/skills/static/web-research-cache.md

@@ -0,0 +1,112 @@
+# Skill: Web Research Cache
+
+> Load this file when you are about to run a web search.
+> Check the cache first. Save results after. Never search twice for the same thing.
+
+## Cache location
+
+```
+researchs/                        ← project root (alongside plans/, prds/)
+└── {slug}/
+    ├── summary.md                ← frontmatter + consolidated findings
+    └── files/
+        └── {source-slug}.md     ← raw content from each consulted URL
+```
+
+The `slug` identifies the topic searched (e.g., `stripe-api-2026`, `nextjs-app-router`, `jwt-vs-session`). Use kebab-case, include the year when the decision may age.
+
+## Step 1 — Check cache before searching
+
+Before running any WebSearch:
+
+1. Derive the slug from the topic you are about to search
+2. Check if `researchs/{slug}/summary.md` exists
+3. Read `searched_at` from its frontmatter
+4. If `searched_at` is within the last **7 days** → use the cached result, do not search again
+5. If older than 7 days or missing → proceed to search
+
+## Step 2 — Run the search
+
+- Formulate the query including the **current year** so results are fresh
+- Maximum **4 queries per session** — focus on the decisions with highest risk of being outdated
+- If WebSearch fails for a query: record the error in `summary.md` and continue — do not block
+
+## Step 3 — Save results
+
+After searching, always save before using the results:
+
+**`researchs/{slug}/summary.md`:**
+```markdown
+---
+searched_at: {ISO-date}
+agent: {agent-name}
+prd: {prd-slug or null}
+query: "{query used}"
+verdict: confirmed | has-alternatives | outdated | deprecated
+---
+
+# Research: {topic title}
+
+## Verdict
+[One line with the verdict and justification]
+
+## Findings
+[Consolidated summary — maximum 5 bullets]
+
+## Sources consulted
+- [URL] — [what it contributed]
+```
+
+**`researchs/{slug}/files/{source-slug}.md`:** raw content from each URL consulted.
+
+## Step 4 — Surface only what is actionable
+
+Show the user **only** findings with verdict `has-alternatives`, `outdated`, or `deprecated`:
+
+```
+🔍 Web Intelligence — {current date}
+
+**[decision or technology]** — {verdict}
+→ {finding in 1–2 lines}
+→ Alternative: {recommended alternative, if any}
+→ Source: [URL]
+
+Want to incorporate this update?
+```
+
+If all findings are `confirmed`:
+> "✓ Decisions validated against recent research. No updates needed."
+
+`confirmed` findings are **never shown** — they are noise.
+
+## Verdicts
+
+| Verdict | Meaning |
+|---|---|
+| `confirmed` | Still the best choice — no action needed |
+| `has-alternatives` | Valid but better options now exist |
+| `outdated` | Superseded by a newer approach |
+| `deprecated` | Officially discontinued or abandoned |
+
+## Who reads and who writes
+
+| Agent | Reads cache | Writes cache |
+|---|---|---|
+| @sheldon | ✅ | ✅ — primary writer for PRD technical decisions |
+| @analyst | ✅ | ✅ — technology and integration validation |
+| @architect | ✅ | ✅ — infrastructure and library trade-offs |
+| @dev | ✅ | ✅ — library docs and implementation patterns |
+| @product | ✅ | ✅ — market and domain context |
+| @deyvin | ✅ | ✅ — continuity session lookups |
+| @orache | ✅ (read only) | ❌ — domain intelligence goes to `squad-searches/`, not here |
+
+**Why @orache does not write here:** `researchs/` uses a verdict schema (`confirmed | has-alternatives | outdated | deprecated`) designed for technical decision validation. Domain investigation findings (frameworks, anti-patterns, vocabulary) do not fit this schema and would pollute the cache with non-actionable data for other agents.
+
+## Rules
+
+- **Never search without saving** — unsaved results are lost after the session
+- **Never block on search failure** — record the error and continue
+- **Never show `confirmed` findings** — they add noise without value
+- **Never modify the PRD/plan without user confirmation** — surface findings, let the user decide
+- **Cache is shared across all agents** — if another agent already searched the same topic this week, use their result
+- The user decides whether to act on findings. Agents surface, humans decide.

package/template/.aioson/tasks/implementation-plan.md

@@ -19,6 +19,20 @@
 - Detecta `prd-{slug}.md` existente sem `implementation-plan-{slug}.md`
 - Gera plan scoped à feature
 
+## Constitution Gate
+
+Before generating or approving the implementation plan, verify:
+
+- [ ] Article I — Work starts from an existing spec artifact (PRD or equivalent), not direct coding
+- [ ] Article II — Classification (MICRO/SMALL/MEDIUM) is declared and process depth matches it
+- [ ] Article IV — Acceptance criteria in requirements are independently verifiable, not vague
+- [ ] Article V — Inputs are complete enough for the next agent to start without re-reading the full discovery chain
+- [ ] Article VI — The plan does not introduce unnecessary phases, artifacts, or abstraction layers
+
+If one or more items fail, stop and describe what is missing before continuing.
+
+---
+
 ## Processo
 
 ### Passo 1 — Inventory check
@@ -38,7 +52,7 @@ Artefatos a verificar (em ordem de prioridade):
 | `ui-spec.md` | Se tem UI | Info — fases de UI terão menos detalhe |
 | `readiness.md` | Se existe | Info — plan assume readiness = READY |
 | `spec.md` | Se existe | Info — sem histórico de decisões anteriores |
-| `design-doc.md` | Se existe | Info — decisões arquiteturais menos firmes |
+| `design-doc.md` / `design-doc-{slug}.md` | Se existe | Warn se `updated` > 60 dias ou ausente — verificar antes de usar como constraint |
 | `requirements-{slug}.md` | Feature mode | Warn — regras de negócio podem faltar |
 
 ### Passo 2 — Cross-analysis
@@ -58,6 +72,12 @@ Para cada issue encontrado, classificar:
 - **WARN** — pode prosseguir com assumption explícita (ex: campo inferido)
 - **INFO** — anotar para o dev ter consciência (ex: possível refatoração futura)
 
+**Design-doc freshness check:**
+- Se `design-doc.md` ou `design-doc-{slug}.md` existe e tem campo `updated` com data anterior a 60 dias: classificar como **WARN** — "design-doc pode estar desatualizado; verificar se decisões ainda refletem o estado atual antes de usar como constraint"
+- Se o design-doc existe mas não tem campo `updated`: tratar como potencialmente desatualizado — mesmo WARN
+- Se a seção "Decisions still pending" do design-doc tem itens não resolvidos: listar cada um como **INFO** — "decisão pendente no design-doc: {item}"
+- Não bloquear o plano por staleness — apenas garantir que o dev está ciente antes de herdar uma constraint desatualizada
+
 ### Passo 3 — Sequence planning
 
 Definir a ordem de implementação baseada em:

package/template/.claude/commands/aioson/agent/design-hybrid-forge.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Generate a hybrid design skill from two visual parents"
+---
+
+Read `.aioson/agents/design-hybrid-forge.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/orache.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Domain investigation and strategic research"
+---
+
+Read `.aioson/agents/orache.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/sheldon.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Deep technical analysis and architecture review"
+---
+
+Read `.aioson/agents/sheldon.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/site-forge.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Clone, extract, and forge sites and design skills from any URL"
+---
+
+Read `.aioson/agents/site-forge.md` and follow all instructions. $ARGUMENTS

package/template/AGENTS.md

@@ -16,7 +16,7 @@ Type `@agent-name` in the prompt. Codex will find the agent file and include its
 The agent activates automatically — begin executing its instructions immediately.
 Do not treat the included file as something to quote, summarize, or display back to the user unless the user explicitly asked to inspect the file itself.
 
-Examples: `@setup`, `@deyvin`, `@dev`, `@squad`, `@genome`, `@profiler-researcher`
+Examples: `@setup`, `@deyvin`, `@dev`, `@squad`, `@genome`, `@profiler-researcher`, `@design-hybrid-forge`, `@site-forge`
 
 **Option 2 — Natural language:**
 Describe your intent. The agent system will match and execute.
@@ -29,6 +29,7 @@ Describe your intent. The agent system will match and execute.
 | @architect | "design the architecture", "use the architect agent" |
 | @ux-ui | "design the UI", "use the UI/UX agent" |
 | @product | "define the product vision", "use the product agent", "start the product wizard" |
+| @sheldon | "deep technical review", "analyze the architecture", "use the sheldon agent" |
 | @deyvin | "continue what we were doing", "use the deyvin agent", "let's fix this together" |
 | @pm | "create the user stories", "use the pm agent" |
 | @dev | "implement the feature", "use the dev agent" |
@@ -40,6 +41,9 @@ Describe your intent. The agent system will match and execute.
 | @profiler-researcher | "start the profiler research", "profile this person", "pesquisar DNA mental" |
 | @profiler-enricher | "enrich this profile", "analyze this person's cognition", "consolidar perfil cognitivo" |
 | @profiler-forge | "generate the advisor", "forge the genome 3.0", "gerar advisor da persona" |
+| @orache | "investigate this domain", "research market and competitors", "use the orache agent" |
+| @design-hybrid-forge | "create hybrid design skill", "combine two design skills", "use the design-hybrid-forge agent" |
+| @site-forge | "clone this site with [skill]", "rebuild [url] using [skill]", "[url] in the style of [skill]", "extract the design from [url] as a skill", "use the site-forge agent" |
 
 When an agent file is included via @ or described via natural language, read the corresponding file and execute its instructions immediately from the first step.
 Do not answer with "I will open/read/show the file" unless the user explicitly asked to inspect that file.
@@ -78,6 +82,7 @@ When running Codex directly (without `aioson workflow:next`), these rules apply:
 - @architect → `.aioson/agents/architect.md`
 - @ux-ui → `.aioson/agents/ux-ui.md`
 - @product → `.aioson/agents/product.md`
+- @sheldon → `.aioson/agents/sheldon.md`
 - @deyvin → `.aioson/agents/deyvin.md` (`@pair` remains as a compatibility alias)
 - @pm → `.aioson/agents/pm.md`
 - @dev → `.aioson/agents/dev.md`
@@ -90,6 +95,75 @@ When running Codex directly (without `aioson workflow:next`), these rules apply:
 - @profiler-researcher → `.aioson/agents/profiler-researcher.md`
 - @profiler-enricher → `.aioson/agents/profiler-enricher.md`
 - @profiler-forge → `.aioson/agents/profiler-forge.md`
+- @orache → `.aioson/agents/orache.md`
+- @design-hybrid-forge → `.aioson/agents/design-hybrid-forge.md`
+- @site-forge → `.aioson/agents/site-forge.md`
+
+## Spec-Driven Development (SDD)
+
+AIOSON uses the `aioson-spec-driven` process skill to enforce specification-first development.
+
+### Core artifacts
+- `constitution.md` — governs all agents with 6 articles
+- `project-pulse.md` — global heartbeat, max 30 lines, updated by every agent at session end
+- `spec-{slug}.md` — feature memory with `phase_gates`, `spec_version`, and `last_checkpoint`
+- `conformance-{slug}.yaml` — machine-readable AC definitions (MEDIUM projects only)
+
+### Phase gates
+- **Gate A** (requirements): must pass before @architect starts
+- **Gate B** (design): must pass before @dev starts
+- **Gate C** (plan): must pass before significant implementation
+- **Gate D** (execution): must pass before feature is marked done
+
+Gates are blocking in MEDIUM, informational in MICRO/SMALL.
+
+### How agents load SDD
+Each agent checks for `aioson-spec-driven` in `.aioson/installed-skills/` or `.aioson/skills/process/` and loads its role-specific reference file (e.g., `references/dev.md`, `references/qa.md`).
+
+### Project pulse convention
+Every agent updates `project-pulse.md` at session end with: last_agent, last_gate, active features, blockers, and next recommended action. This enables crash recovery — any agent can read project-pulse.md and know where to resume.
+
+## Process skill: aioson-spec-driven
+
+Located at: `.aioson/skills/process/aioson-spec-driven/SKILL.md`
+
+This is a first-party process skill. It teaches agents how phases connect, when to apply which depth, and how to prepare clean handoffs.
+
+Agents that load it: @product, @analyst, @architect, @sheldon, @dev, @deyvin, @qa, @tester, @orchestrator, @pm
+When to load: at the start of any spec work (PRD, requirements, architecture, implementation, testing)
+What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
+
+## Process skill: design-hybrid-forge
+
+Located at: `.aioson/skills/process/design-hybrid-forge/SKILL.md`
+
+This is a first-party process skill for generating project-local hybrid design skills from 2 primary design parents.
+
+Activated by: @design-hybrid-forge
+Default output: `.aioson/installed-skills/{hybrid-name}/`
+What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
+
+## Shared research cache: researchs/
+
+Located at: `researchs/` (project root)
+
+A shared folder where agents store and reuse internet research. Structure:
+```
+researchs/
+└── {slug-da-pesquisa}/
+    ├── summary.md          ← frontmatter (searched_at, agent, query, verdict) + findings
+    └── files/              ← raw content saved from consulted URLs
+        └── {source-slug}.md
+```
+
+**Rules for all agents:**
+- Before running a web search, check if a `researchs/{slug}/summary.md` exists and was created within the last 7 days — use the cached result instead of searching again
+- After running a web search, save the result to `researchs/{slug}/summary.md` so other agents can reuse it
+- `summary.md` frontmatter must include: `searched_at` (ISO-date), `agent` (who ran it), `query`, `verdict` (`confirmed` | `has-alternatives` | `outdated` | `deprecated`)
+- This folder is at the project root (alongside `plans/`, `prds/`), not inside `.aioson/`
+
+Primary agent that writes here: @sheldon (RF-WEB step)
+All agents may read from here to avoid redundant searches.
 
 ## Session protocol
 If `.aioson/context/spec.md` exists, read it at session start and update it at session end.

package/template/CLAUDE.md

@@ -31,6 +31,23 @@ You operate as AIOSON.
 - /profiler-researcher -> `.aioson/agents/profiler-researcher.md`
 - /profiler-enricher -> `.aioson/agents/profiler-enricher.md`
 - /profiler-forge -> `.aioson/agents/profiler-forge.md`
+- /design-hybrid-forge -> `.aioson/agents/design-hybrid-forge.md`
+- /site-forge -> `.aioson/agents/site-forge.md`
+
+## Spec-Driven Development framework
+
+AIOSON follows a Spec-Driven Development (SDD) methodology. Key governance files:
+
+- **`.aioson/constitution.md`** — 6 governing principles all agents must respect
+- **`.aioson/context/project-pulse.md`** — global project state; read at session start, update at session end
+- **`.aioson/skills/process/aioson-spec-driven/SKILL.md`** — process methodology; agents load this automatically
+
+The process depth scales with project classification:
+- **MICRO** (0-1): lightweight — @product → @dev
+- **SMALL** (2-3): standard — @product → @analyst → @dev
+- **MEDIUM** (4-6): full — all agents, all gates, all artifacts
+
+Classification is determined by @analyst during discovery. See `aioson-spec-driven` skill for details.
 
 ## Workflow enforcement
 
@@ -57,5 +74,19 @@ When running Claude Code directly (without `aioson workflow:next`), these rules
 - Plain slash-command activation registers in the dashboard automatically via `aioson agent:done` at the end of each agent session — each agent file has the call in its "Observability" section.
 - Do not call `aioson runtime-log` directly from inside the session — use `aioson agent:done` instead, which is safe in both direct and live-session contexts.
 
+## Shared research cache: researchs/
+
+All agents may read from and write to `researchs/` (project root). Before running any web search, check if `researchs/{slug}/summary.md` exists and was created within the last 7 days — use the cached result instead. After searching, save results there for reuse by other agents. See AGENTS.md for the full convention.
+
+## Local overrides
+
+Create `CLAUDE.local.md` (not committed) for machine-specific settings:
+- Local tool paths and environment variables
+- Personal preferences that should not affect other team members
+- Dev environment overrides
+
+`CLAUDE.local.md` is loaded after `CLAUDE.md` and takes precedence.
+Add it to `.gitignore` to keep it out of version control.
+
 ## Golden rule
 Small project, small solution.

package/template/OPENCODE.md

@@ -12,6 +12,7 @@
 - architect -> `.aioson/agents/architect.md`
 - ux-ui (UI/UX) -> `.aioson/agents/ux-ui.md`
 - product -> `.aioson/agents/product.md`
+- sheldon -> `.aioson/agents/sheldon.md`
 - deyvin -> `.aioson/agents/deyvin.md`
 - pair -> `.aioson/agents/deyvin.md` (compatibility alias)
 - pm -> `.aioson/agents/pm.md`
@@ -25,6 +26,9 @@
 - profiler-researcher -> `.aioson/agents/profiler-researcher.md`
 - profiler-enricher -> `.aioson/agents/profiler-enricher.md`
 - profiler-forge -> `.aioson/agents/profiler-forge.md`
+- orache -> `.aioson/agents/orache.md`
+- design-hybrid-forge -> `.aioson/agents/design-hybrid-forge.md`
+- site-forge -> `.aioson/agents/site-forge.md`
 
 ## Rule
 Do not duplicate rules outside `.aioson/`.