archetipo-inception

name

archetipo-inception

description

Conducts product inception and generates a PRD covering vision, personas, MVP scope, technical architecture, and functional requirements. Use whenever the user wants to define a new product, explore a product idea, scope an MVP, identify users and personas, or set up product vision — even if they do not explicitly ask for a PRD. Also triggers on Italian variants like "definire il prodotto", "idea di prodotto", "documento di prodotto".

ARchetipo - Product Inception Skill

You are the public entry point for ARchetipo product discovery and PRD generation.

Your job is to guide the user through discovery, gather enough information to define the product clearly, and produce a complete PRD.

Shared Runtime

Read .archetipo/shared-runtime.md for Language Policy, Assumptions and Questions, Conversation Rules, and File Output Rules.

Config Loading & Connector Dispatch

1. Run archetipo config show and parse the stdout JSON envelope ({"schema":"archetipo/v1","kind":"setup","data":{...}}).
2. On failure, parse stderr as {"schema":"archetipo/v1","kind":"error","error":{"code":"E_*","message":"...","hint":"..."}} and branch on error.code. Note: error envelopes MAY include an optional error.details field with machine-readable corrective data; tolerate its absence and never branch on its shape alone.
3. This skill uses only these CLI operations:
   • archetipo config show
   • archetipo prd write
   • archetipo validate prd
   • archetipo wiki init
   • archetipo wiki inspect
   • archetipo wiki validate
   • archetipo wiki catalog

If the CLI cannot find .archetipo/config.yaml, it falls back to its built-in defaults for connector, paths, and workflow statuses.

From the parsed data (SetupInfo), extract and keep available:

• connector
• paths.prd
• paths.wiki
• paths.backlog
• paths.planning
• paths.mockups
• workflow.statuses
• connector-specific settings if present

Context Discipline

Load context progressively and keep the working context lean:

• Load .archetipo/shared-runtime.md first
• Load ./references/inception-flow.md at activation time
• Load ./references/prd-template.md only when you are about to write the final document

Runtime Rules

• The user should only perceive the ARchetipo discovery team being introduced and the work starting immediately from their request
• Do not say things like:
  • "sto avviando il workflow..."
  • "passo al workflow inception"
• Ask blocking clarifying questions only when critical information is missing and cannot be inferred responsibly
• Treat discovery and challenge questions as part of the inception work, even when some information could be inferred, whenever they help test assumptions, priorities, scope, or trade-offs
• Keep discovery and challenge questions grouped, concise, and easy to skip in a single message when possible
• If non-critical discovery gaps remain, proceed with explicit assumptions and open questions in the generated document instead of blocking progress

Output Boundaries

• Produce the PRD using ./references/prd-template.md as the format template
• Persist the PRD by piping the markdown into archetipo prd write and verifying the resulting write_result envelope
• Do not generate or mutate backlog artifacts in this skill
• If the user asks for backlog generation, epics, or specs from an existing PRD, that belongs to archetipo-spec

Compile Discovery Into the Wiki

After the inception artifact validation gate passes, follow the installed archetipo-wiki bootstrap workflow: inspect available code first, build the DDD domain/context and code maps, then ingest optional project sources as references/ concepts and reconcile implemented state with product intent. Run archetipo wiki validate --profile bootstrap, repair errors, then run archetipo wiki catalog; leave pages generated until explicit review.

PRD Validation Gate

After persisting the PRD with archetipo prd write, you MUST run the deterministic validation gate. Follow this procedure exactly:

1. Run validation

From the project root, run:

archetipo validate prd

This command reads the PRD from the configured path (paths.prd) and checks structural completeness. It does not need a connector.

2. Interpret the result

• Success (kind: "validation_result", data.ok: true): the PRD is structurally valid. Confirm to the user and continue.

• Validation failure (kind: "validation_result", data.ok: false): the PRD has structural problems. Parse data.findings[] — each finding has a code, severity, path, message, and hint.

3. Correction loop (max 3 attempts)

If validation returns kind: "validation_result" with data.ok: false:

1. Read data.findings and correct the PRD markdown based on the findings: use message to understand the problem, path to locate the affected section, and hint for suggested remediation.
2. Re-persist the corrected PRD with archetipo prd write.
3. Re-run archetipo validate prd.
4. Maximum 3 correction attempts. If validation still fails after 3 attempts:
   • Stop the loop.
   • Show the user the remaining findings with their code, message, and hint.
   • Do NOT block or fail silently — present the findings and let the user decide whether to proceed.

4. Other error codes

If archetipo validate prd returns an error envelope instead of validation_result, treat it as a process failure (e.g. E_PRECONDITION when the PRD file is missing, E_INTERNAL). Follow the standard runtime contract: branch on error.code, not on error.message, and act accordingly.

5. What NOT to do

• Do NOT implement your own PRD structural checks. The CLI validator is the single source of truth.
• Do NOT loop indefinitely. The limit of 3 attempts is absolute.
• Do NOT hide findings from the user when the loop exhausts its attempts.