# Pyramid Method and Per-step Instructions

Assembly Hangar is built around a fixed 13-step method. Use it always: to build
the system itself and as the thinking framework the system applies to customer
projects. The code source of truth for the steps is the project step registry;
keep this document, the rules and the registry aligned.

> First overview, then depth, then action. First structure, then layout.
> Not every piece of information deserves its own block.

The AI must not skip steps unless the current task is explicitly limited to a
lower-level implementation detail. Even then, briefly identify where the task
sits in the pyramid.

For each step: Purpose, what the AI must do, what the AI must inspect, what is
good enough, what is not good enough, and required output.

The build-up engine (module -> feature -> epic -> story -> task -> subtask)
backs steps 4, 6 and 10. Steps 3, 7, 8, 9 and 12 capture structured step content
(use cases, data model, integrations, architecture, code reviews).

## 1. Northstar
- Purpose: define what the product is trying to achieve: what, for whom, which problem, and the desired end state. The codebase context and audit live here.
- Do: rewrite vague goals into clear outcomes; for an existing project derive the Northstar from the codebase and docs; before asking about languages, frameworks, build tools, package manager, database, tests, CI/CD or deployment, inspect repository/audit evidence and record the actual facts plus exact install/test/build commands.
- Inspect: project descriptions, README, product docs, repo structure, manifest files, lockfiles, framework configs, workflow/deployment files, adoption audit findings.
- Good enough: one or two clear sentences describing the outcome, usable to guide decisions; repository-answerable technical facts are listed from evidence instead of left as user questions.
- Not good enough: "improve dashboard", "make it better"; treating an existing project as a blank slate.
- Output: a clear Northstar statement, why it matters, input summary, stack/evidence summary for imported codebases and only missing product/business/domain context.

## 2. Audience, users and roles
- Purpose: decide who uses the product and which roles, needs and permissions exist. This is about roles inside the BUILT product (Owner, Admin, Developer, Designer, Agent, Customer, Viewer), not Assembly Hangar's own roles.
- Do: identify user groups and roles; capture per module what each role may view or change.
- Inspect: auth logic, role checks, user model, permission utilities.
- Good enough: intended roles defined with a per-module access matrix; sensitive actions separated.
- Not good enough: everyone sees everything; fake frontend-only security.
- Output: role list, per-module permission assumptions, risks.

## 3. Problem, use cases and scenarios
- Purpose: translate the Northstar into real usage situations, linked to roles and prioritized.
- Do: derive concrete use cases ("As <role> I want <action> so that <outcome>"); name edge cases; set priority; suggest grounded use cases and let the human accept or park.
- Inspect: the Northstar, requirements, existing flows, feedback.
- Good enough: specific use cases tied to a role and prioritized; edge cases noted.
- Not good enough: restating the goal; generic use cases with no actor or outcome.
- Output: prioritized use cases/scenarios with actor, action and outcome.

## 4. Feature map
- Purpose: turn use cases and requirements into concrete modules and features.
- Do: generate or refine the module/feature build-up; ensure modules map to real capabilities; avoid module explosion.
- Inspect: existing modules/features, navigation, accepted requirements.
- Good enough: each module has a clear purpose; features belong to the right module.
- Not good enough: modules/features created because they sound useful.
- Output: module and feature map with purpose and relationships.

## 5. Requirements and acceptance criteria
- Purpose: make features testable; fix the scope before building further.
- Do: generate requirements; accept what is correct and supersede/park what is wrong; attach acceptance criteria.
- Inspect: the Northstar, use cases, existing behavior, adoption findings.
- Good enough: accepted requirements with acceptance criteria; scope is clear.
- Not good enough: requirements without priority or acceptance criteria; accepting everything blindly.
- Output: requirement list with status, priority and acceptance criteria.

## 6. UX, screens and navigation
- Purpose: define the screens (story level) and navigation.
- Do: define page hierarchy and overview-vs-detail; make the next step obvious; structure before layout.
- Inspect: routes, layout components, sidebar/menu definitions, crowded screens.
- Good enough: every screen has one clear primary purpose; navigation is predictable per role.
- Not good enough: one page does everything; detail before context; the same info in many places.
- Output: screen list with purpose, sections, primary action and detail-access pattern.

## 7. Data, database and permissions
- Purpose: define the data model and confirm it fits the screens and roles.
- Do: describe entities, fields and relationships; confirm access and tenant/audit needs.
- Inspect: existing schema/migrations, models, the module/feature map, role matrix.
- Good enough: entities and relationships are clear and aligned with screens and roles.
- Not good enough: vague data notes; data that does not support the defined screens.
- Output: data entities with fields, relationships and access notes.

## 8. Integrations, APIs and automations
- Purpose: describe integrations and API couplings.
- Do: list integrations and data flows; note auth method, direction and failure handling; mark explicitly when none are needed.
- Inspect: integration requirements, existing connections/settings, external systems referenced.
- Good enough: each integration has purpose, auth and direction; "none needed" stated when true.
- Not good enough: integrations without auth/direction; ignoring obvious dependencies.
- Output: integration list with auth, direction and data-flow notes.

## 9. Architecture and technical blueprint
- Purpose: capture the technical blueprint and key decisions.
- Do: record decisions with rationale, risk and alternatives; show how frontend, backend, data, AI layer and deployments fit together.
- Inspect: decision logs, technical requirements, adoption findings, architecture docs.
- Good enough: decisions are explicit, justified and risk-aware.
- Not good enough: undocumented choices; "use best practices" without specifics.
- Output: architecture decisions with rationale, risk and alternatives.

## 10. Planning, tasks and dependencies
- Purpose: turn everything into executable work.
- Do: confirm the task level (priority, dependencies, owner, status); make blockers explicit.
- Inspect: the node tree (task level), dependencies, existing agent tasks.
- Good enough: tasks prioritized, ordered and owned; blockers visible.
- Not good enough: an unordered task dump; hidden dependencies.
- Output: task list with priority, dependencies, owner and status.

## 11. Agent execution and work packages
- Purpose: generate and manage the agent plan.
- Do: generate work packages with scope, instruction, acceptance criteria and owner agent; track status and link PRs.
- Inspect: the task level, agent task records, GitHub/PR metadata.
- Good enough: work packages scoped, instructed and trackable per agent.
- Not good enough: vague packages without scope or acceptance criteria.
- Output: agent work packages with scope, instructions, acceptance and status.

## 12. Code review, tests and quality
- Purpose: the quality gate. Run an extensive, repo-wide audit (real scanners in an isolated sandbox: dependencies, secrets, SAST, vulnerable config) and check built changes for quality, scope, safety and acceptance criteria; record a go/no-go. Also validate the fixed UX criteria. Same audit engine runs at intake on step 1 (baseline) and here on step 12 (quality gate).
- Do: run/read the codebase audit and turn scanner output into structured findings with severity and a quality + security score; review changes against scope and acceptance; validate build/type/lint status and pyramid fit; record findings and a go/no-go.
- Inspect: audit findings and score, scanner outputs, completed agent tasks, pull requests, test/build output, the screens and requirements satisfied.
- Good enough: the audit ran and its findings/score are recorded; reviews state what was checked and the result; clarity improved; limitations documented.
- Not good enough: "done" without testing or audit; ignoring build errors or critical findings; shipping changes that break the flow.
- Output: an audit run with findings, score and go/no-go, plus reviews with checks run, result, known issues and acceptance status.

## 13. Versioning, releases and changelog
- Purpose: make every meaningful change traceable and releasable.
- Do: record what changed, why, files touched, tests run, risks and rollback notes; register and approve releases.
- Inspect: releases, feature versions, the latest changes and their impact.
- Good enough: another agent can understand the change; rollback is possible or limits are known.
- Not good enough: silent changes; no changelog; no file summary.
- Output: changelog entry, files changed, reason, test result, remaining work.

## Final checklist (before finishing any task)

1. Where does this task sit in the pyramid?
2. What problem did I solve?
3. Did I inspect existing structure first?
4. Did I put the change in the right place?
5. Did I avoid adding visual noise?
6. Did I avoid duplication?
7. Did I keep settings centralized?
8. Did I make the workflow clearer?
9. Did I test or validate the change?
10. Did I document what changed?

If the answer to any of these is unclear, the task is not finished.