ARchetipo Documentation

Quick start

Install the ARchetipo CLI globally with one npm command.

npm install -g @techreloaded/archetipo

# verify installation and version
archetipo version

Initialize a project

After the global installation, before using ARchetipo in a project you need to initialize it inside that project directory:

$ cd my-project
$ archetipo init

# or non-interactively:
$ archetipo init --tool claude --connector file

What archetipo init does

• Copies the ARchetipo skills into the selected AI tool directory, for example .claude/skills/ or .gemini/skills/.
• Creates .archetipo/config.yaml with the selected connector (file by default).
• Creates .archetipo/shared-runtime.md with the project runtime rules.
• Can run interactively (archetipo init) or non-interactively with flags such as --tool, --connector and --yes.

Glossary

Core concepts that appear throughout the documentation and skills.

Term	Meaning
PRD	Product Requirements Document: defines what to build, for whom and why. It is the starting point of the pipeline.
Backlog	Ordered list of user stories to implement, each with priority, estimate and state (TODO -> PLANNED -> IN PROGRESS -> REVIEW -> DONE).
User story	Atomic requirement from the user's point of view: "As <persona> I want <action> so that <benefit>".
Epic	Group of related user stories with a shared goal. Each story belongs to an epic.
Planning	Technical document for a single story with solution, ordered tasks, dependencies and test strategy. Saved by the file connector in .archetipo/plans/US-XXX-plan.yaml.
Acceptance criteria	Verifiable conditions that define when a story can be considered complete.
Connector	Persistence mode for project artifacts: local file system through the ARchetipo CLI, or GitHub Projects v2 + Issues.

How to use it

The workflow

After installation, follow this flow in your AI coding agent. Each slash-command invokes a skill that produces persistent artifacts and feeds the next phase.

ARchetipo implements Spec-Driven Development: the specification is the contract, and the spec -> plan -> implement cycle repeats for every value slice until the product is complete.

STEP 01 · DISCOVERY: define the product

Command: /archetipo-inception

Discovery and product definition. Guides discovery with a virtual team. Collects goals, scope and business assumptions, and produces the PRD.

• Prerequisite: none
• Team: Andrea, Costanza, Leonardo, Livia, Emanuele
• Output: docs/PRD.md

STEP 02 · OPTIONAL: create visual concepts

Command: /archetipo-design

UI mockups and prototypes. Produces isolated HTML/CSS mockups in docs/mockups/ without touching application code. They are used as visual reference by archetipo-implement.

• Prerequisite: none
• Team: Livia
• Output: docs/mockups/

STEP 03 · BACKLOG: generate the initial backlog

Command: /archetipo-spec

Backlog creation and extension. Converts the PRD into a backlog or adds new INVEST-compliant stories to an existing backlog, with challenging quality questions. It auto-detects the mode.

• Prerequisite: existing PRD
• Team: Andrea, Emanuele
• Output: .archetipo/backlog.yaml

STEP 04 · PLANNING: plan a story

Command: /archetipo-plan US-001

Technical implementation plan. Turns a TODO story into a technical plan with solution, ordered tasks, dependencies and test strategy, including e2e tests with video recording.

• Prerequisite: story already present in the backlog
• Team: Emanuele, Leonardo, Ugo, Mina
• Output: .archetipo/plans/US-001-plan.yaml

STEP 05 · CODE: implement the code

Command: /archetipo-implement US-001

Code and test writing. Executes the technical plan: writes code, unit/integration/e2e tests, runs automatic code review and moves the story toward REVIEW.

• Prerequisite: planning file, story PLANNED
• Team: Ugo, Mina, Cesare
• Output: code, tests, review notes

Language auto-detection

Each skill automatically adopts the language of the conversation. Write in Italian, get Italian artifacts. Write in English, get English artifacts.

Workflow states

Stories move through standardized states. Automatic transitions happen during the loop; the final move to DONE is always manual.

State	Meaning	Transition
TODO	Story in the backlog, not started	automatic, from spec
PLANNED	Technical planning completed	automatic, from plan
IN PROGRESS	Implementation in progress	automatic, from implement
REVIEW	Code review and tests passed, ready for human approval	automatic, end of implement
DONE	Story accepted and released	manual

Where do I start?

Quick guide to choosing the right skill based on your project phase. Follow the questions in order.

Question	If the answer is no	If the answer is yes
Do you already have a PRD?	Use /archetipo-inception.	Continue.
Do you want visual concepts before development?	Skip design for now.	Use /archetipo-design.
Do you already have a backlog of stories?	Use /archetipo-spec.	Continue.
Are the stories already planned?	Use /archetipo-plan US-001 on a TODO story.	Continue.
Is a story ready to implement?	Plan it first.	Use /archetipo-implement US-001.

CLI and available commands

ARchetipo uses a CLI written in Go, archetipo, which implements configuration and persistence operations for project artifacts.

In normal ARchetipo usage, you interact with the /archetipo-* skills and they autonomously invoke the necessary commands based on the project state. The CLI reads .archetipo/config.yaml from the repository to know the current configuration.

The only commands that are genuinely useful to run manually in day-to-day use are these:

archetipo init

Installs ARchetipo in the current repository: copies the skills into the selected AI tool and creates .archetipo/config.yaml plus .archetipo/shared-runtime.md.

archetipo init

# or non-interactively
archetipo init --tool claude --connector file

archetipo view

Starts the local backlog view as a Kanban board. It is especially useful with the file connector because it reads and displays the artifacts saved under .archetipo/.

archetipo view

archetipo version

Shows the installed CLI version. It is useful immediately after npm install -g @techreloaded/archetipo to verify that installation succeeded and check which release you are using.

archetipo version

All other CLI subcommands exist mainly as the technical surface used internally by the skills to read the backlog, save plans, update states and complete tasks.

Connector

ARchetipo does not bind the workflow to a single storage system. It works on a stable set of project artifacts and uses a connector to decide where these artifacts are read, saved and updated. This keeps the method identical even when the storage target changes: a local repository when you want to work independently, GitHub when you want shared tracking and a cloud board.

In practice, the skills always reason over the same concepts — PRD, backlog, spec, plans, tasks, mockups — while the connector translates these operations into the persistence system configured in .archetipo/config.yaml.

ARchetipo artifacts

Artifact	What it is	What it is for
PRD	Vision and high-level requirements document.	Aligns goals, personas, scope and constraints before building the backlog.
Backlog	Ordered view of the specs to build.	Makes priorities, progress status and project epics visible.
Spec	Structured specification card with title, body, acceptance criteria, priority and status.	It is the work unit that moves through the spec -> plan -> implement cycle.
Technical plan	Implementation translation of a spec: solution, ordered tasks, dependencies and test strategy.	Guides implementation without leaving operational ambiguity to the agent.
Task	Executable steps that make up a technical plan.	Enable granular and verifiable work tracking.
Mockup	UI concepts isolated from application code.	Provide a visual reference for the implementation phase.

How a connector works

• The skill reads .archetipo/config.yaml to know which connector is active.
• ARchetipo invokes the same CLI commands, regardless of the selected connector.
• The connector translates read and write operations into the correct system: local files or GitHub.

Result: you can change where your artifacts live without rewriting skills, prompts or product process.

Where artifacts live

Artifact	file connector	github connector
PRD	docs/PRD.md	docs/PRD.md
Backlog	.archetipo/backlog.yaml	Issues on the GitHub Projects v2 board
Spec	.archetipo/specs/US-XXX.yaml	Parent issue with story body and board metadata
Technical plan	.archetipo/plans/US-XXX-plan.yaml	Added to the parent issue body
Task	In the spec YAML plan	Sub-issues linked to the story
Mockup	docs/mockups/	docs/mockups/
Board and states	Local board via archetipo view	GitHub Projects v2 with custom fields

File connector

This is the default connector. It keeps backlog, specs and plans in the repository, with no authentication and full versionability. It is ideal for individual work, rapid experimentation and offline contexts. The local board from archetipo view reads these artifacts and makes them navigable as a Kanban board.

GitHub connector

Moves the workflow onto GitHub Projects v2 and GitHub Issues. It is designed for teams that want shared visibility, board progress tracking and executable tasks as sub-issues, while keeping the PRD and mockups as files in the repository.

Extensibility. The built-in connectors today are file and github, but the architecture is designed to allow future targets such as Linear, Jira or Trello.

Configuration

.archetipo/config.yaml defines connector, paths and workflow states. If the file is missing, the CLI uses the default configuration; if some keys are absent, it automatically fills missing values with the official defaults.

connector: file   # file | github

# paths shared by all connectors
paths:
  prd: docs/PRD.md
  mockups: docs/mockups/
  test_results: docs/test-results/

workflow:
  statuses:
    todo: TODO
    planned: PLANNED
    in_progress: IN PROGRESS
    review: REVIEW
    done: DONE   # no skill automatically moves a spec to DONE

# used only when connector == file
file:
  backlog: .archetipo/backlog.yaml
  planning: .archetipo/plans/

# used only when connector == github
github:
  # owner: auto-detected from repo
  # project_number: auto-detected from repo

• connector selects the persistence backend: file or github.
• paths defines paths shared by all connectors: PRD, mockups and test results.
• file contains local connector-specific paths: backlog and planning.
• workflow.statuses allows mapping the status labels used by the project; missing values are filled with defaults.
• github contains optional GitHub connector overrides; owner and project_number are auto-detected if left empty.
• The old paths.backlog and paths.planning fields are no longer valid: they should be migrated respectively to file.backlog and file.planning.

Philosophy

The team is a lens, not a costume

Each persona applies an angle of analysis. The brief is concise and makes the process visible.

Lean context

The skills read only what is needed, in order: shared-runtime -> config -> CLI commands -> template. Large files are read surgically.

Persistent outputs

Each phase produces artifacts that live in the repo or in the connector system. The next command starts from there.

Responsible autonomy

The skills stop only in front of real blockers: external dependencies or ambiguity in the contract. Local adaptations and mechanical fixes do not require confirmation.

Tool and connector agnostic

Changing AI agent or tracking system should not require rewriting the process.

FAQ

Do I always need a PRD to start?

To build a solid backlog, yes: the PRD is the ideal starting point. If it does not exist yet, use archetipo-inception to create it before moving to archetipo-spec.

Can I add stories without rebuilding the whole backlog?

Yes. archetipo-spec distinguishes between initial generation and extension: if the backlog exists, it adds or refines stories without starting from scratch.

Do mockups produced by design end up in application code?

No. archetipo-design produces isolated files in docs/mockups/ used only as visual reference by archetipo-implement, which reads them before writing the real interface.

Can I use ARchetipo on an existing project?

Yes. archetipo-spec in extend-backlog mode adds stories to an existing backlog. archetipo-plan and archetipo-implement work on any story in the backlog, regardless of how it was created.

What happens if my AI tool does not support subagents?

The main skills still work, in in-context mode.

Troubleshooting

The skill cannot find the PRD

Check that paths.prd in .archetipo/config.yaml points to the correct file. The default value is docs/PRD.md.

The GitHub connector does not transition issues

Check that gh is authenticated (gh auth status) and that the token has repo and project scopes. State transitions happen through GraphQL on the Project custom fields.

Artifacts are in the wrong language

The skills detect the language from the latest user message. If the context is mixed, send an explicit message in the desired language before invoking the skill.

Beta Test

ARchetipo is in beta: we have prepared a page with technical documentation, GitHub repository, Discord server and recommended tests to help us improve the workflow on projects, AI agents and real contexts. If you want to participate, you can find resources, feedback channels and operational checklists on the ARchetipo Beta page.

License

MIT © techreloaded. Forks, changes and contributions are welcome: open a PR or a discussion on the repository.

To report bugs, propose features or request support, open an issue on the GitHub repository or join the Discussions.