Adopt an Existing Project

Already have a running project? This guide walks you through onboarding OpenLogos without disrupting your existing codebase. You’ll get the full methodology infrastructure — change management, AI Skills, verify gates — up and running in minutes.

Time required: ~15 minutes to onboard, then iterate at your own pace.

---

How this differs from Quick Start

The Quick Start assumes a brand-new project and walks you through Phase 1 → 2 → 3 from scratch. That’s not your situation.

When you adopt an existing project:

Aspect	New project (init)	Existing project (adopt)
Starting point	Empty directory	Code already exists
Module lifecycle	initial (Phase-driven)	launched (Change-driven)
Phase 1–3 documents	Required before coding	Optional — fill in gradually
Change management	Activates after launch	Active immediately
First suggested action	Write requirements	Create your first change proposal (openlogos change <slug>)

The key difference: adopt sets your module to lifecycle: launched with bootstrap: adopted right away. You skip the initial document baseline requirement and jump straight into the iteration workflow.

---

Step 1: Install OpenLogos CLI

npm install -g @miniidealab/openlogos
openlogos --version

---

Step 2: Run openlogos adopt

From your project root (where package.json, Cargo.toml, or pyproject.toml lives):

openlogos adopt

The CLI will ask two questions:

Choose language / 选择语言:
  1. 中文 (default)
  2. English

Your choice [1/2] (default: 1): 2

Choose AI coding tool / 选择 AI 编码工具:
  1. Claude Code (default)
  2. OpenCode
  3. Codex
  4. Cursor
  5. Other
  6. All (deploy for all tools)

  7. ZCode
  8. Qoder
  9. WorkBuddy

Your choice [1/2/3/4/5/6] (default: 1): 1

Or pass flags to skip the prompts:

openlogos adopt --locale en --ai-tool claude-code

--ai-tool accepts claude-code, opencode, codex, cursor, zcode, qoder, workbuddy, other, or all.

If adopt detects your tech stack, it also lists paths that git does not ignore yet (for example dependency or build output directories) and asks whether to add them to the OpenLogos managed block in .gitignore. You can change this later with openlogos ignore.

What it creates

your-project/
├── AGENTS.md                    ← AI instruction file (auto-generated)
├── CLAUDE.md                    ← Claude Code instruction file
├── .gitignore                   ← OpenLogos managed block (logos/.openlogos-runtime/ + accepted suggestions)
├── .claude/ (or .cursor/, ...)  ← Host integration for the AI tool you chose
│
└── logos/
    ├── logos.config.json        ← Project configuration
    ├── logos-project.yaml       ← AI collaboration index
    │                              (lifecycle: launched, bootstrap: adopted)
    ├── resources/               ← Empty directories, ready to fill
    │   ├── prd/
    │   ├── api/
    │   ├── database/
    │   ├── test/
    │   └── verify/
    ├── skills/                  ← AI Skills (Codex, Cursor, ZCode, Qoder, WorkBuddy load theirs from the host directory)
    ├── spec/                    ← Methodology specifications
    └── changes/                 ← Change proposal workspace

Note

adopt also auto-detects your test command from package.json and configures verify.pre_run_command so openlogos verify knows how to run your tests.

---

Step 3: Configure tech_stack and skip_phases

Open logos/logos-project.yaml and fill in your tech stack. This gives AI the context it needs to generate accurate code and docs.

tech_stack:
  language: TypeScript
  framework: Next.js 15
  database: PostgreSQL
  hosting: Vercel
  auth: NextAuth.js

If your project doesn’t have an HTTP API or database, declare skip_phases to tell OpenLogos which phases to skip:

modules:
  - id: core
    name: Core
    lifecycle: launched
    bootstrap: adopted
    skip_phases: [api, database, scenario]  # CLI tool, no HTTP API

Value	Skips	When to use
api	API design phase	Desktop app, CLI tool, library
database	DB design phase	Stateless service, pure compute
scenario	Orchestration tests	Usually paired with api

---

Step 4: Verify your test setup

Check that openlogos verify can find and run your tests:

cat logos/logos.config.json

You should see a verify section:

{
  "verify": {
    "result_path": "logos/resources/verify/test-results.jsonl",
    "pre_run_command": "npm test"
  }
}

If the pre_run_command is missing or wrong, edit it manually:

{
  "verify": {
    "result_path": "logos/resources/verify/test-results.jsonl",
    "pre_run_command": "npm test",
    "sandbox_mode": "auto"
  }
}

Tip

For projects with separate regression and incremental test suites, use regression_command + incremental_command instead of pre_run_command. See the verify docs for details.

---

Step 5: Check your project status

openlogos status

You’ll see something like:

📊 OpenLogos Project Status

⏭️  Phase 1 · Requirements (WHY) — Documentation baseline skipped (adopted access mode)
⏭️  Phase 2 · Product Design (WHAT) — Documentation baseline skipped (adopted access mode)
⏭️  Phase 3-0 · Architecture — Documentation baseline skipped (adopted access mode)
...

🧩 Modules
  ✅  core (Core)  [launched]
       💡 No standalone baseline is required; run openlogos change <slug> (baseline-seed begin is an explicit optional accelerator)

The ⏭️ phases are skipped — that’s expected. Your project is in launched lifecycle, which means change management is active immediately. Every code change from here on needs a change proposal.

---

Step 6: Start with your first change proposal

You don’t need a standalone baseline proposal before real work. Create a proposal for the first change you actually want to make:

openlogos change my-first-change

This creates logos/changes/my-first-change/ with proposal.md and tasks.md. Tell AI:

Read logos/changes/my-first-change/proposal.md and help me fill it in.

While planning, the change-writer Skill closes over the features and scenarios the change touches: a target spec that already exists is modified; a missing one is created in full, documenting how the touched area works today. Your logos/resources/ grows with each proposal, starting with the areas you actually change.

Tip

Want a code-derived map of the whole codebase up front? The optional brownfield-adopter Skill reverse-scans the code and commits a verified: false system map and scenario candidates through openlogos baseline-seed. It is an explicit accelerator only: status may show baseline_seed_state: required, but that never blocks creating a change.

---

Step 7: Add the OpenLogos reporter to your tests

For openlogos verify to work, your tests need to write results to logos/resources/verify/test-results.jsonl. Add the OpenLogos reporter to your test runner.

Vitest

vitest.config.ts

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    reporters: ['default', './logos/spec/openlogos-reporter.ts'],
  },
});

Jest

jest.config.js

module.exports = {
  reporters: ['default', './logos/spec/openlogos-reporter.js'],
};

pytest

pytest.ini

[pytest]
addopts = --openlogos-reporter

Then name your tests with OpenLogos IDs:

it('UT-S01-01: should register user with valid email', () => { ... });
it('ST-S01-01: full registration flow', () => { ... });

See Test Results Format for the full reporter spec and copy-paste templates.

---

The iteration workflow from here

Once adopted, every change follows the Delta workflow:

1. Create a proposal

   openlogos change my-feature

2. Tell AI to fill in the proposal

   Read logos/changes/my-feature/proposal.md and help me fill it in.

3. Produce delta files — updated specs, API changes, new test cases. openlogos change-lint checks the proposal, tasks, and deltas while they are written, so problems surface before merge.

4. Merge (human confirmation point)

   openlogos merge my-feature

   All deltas are applied in a single atomic call — either everything is written or nothing is.

5. Plan code slices — the slice-planner Skill writes the [code] section of tasks.md with openlogos slice plan --file <slices.json>

6. Implement code + tests — AI implements slice by slice against the merged specs

7. Verify (human confirmation point)

   openlogos verify

8. Archive (human confirmation point; after deployment and smoke if the proposal has a [deploy] section)

   openlogos archive my-feature

---

Common questions

Do I need to fill in all the Phase 1–3 docs before I can do anything?

No. With bootstrap: adopted, Phase 1–3 docs are optional. You can start iterating immediately. Fill them in gradually as you work — each feature proposal is a good opportunity to document the relevant scenarios and architecture decisions.

What if my project has multiple modules?

Run openlogos module add <name> to register additional modules. Each module tracks its own phase progress and lifecycle state independently.

openlogos module add payment
openlogos module add admin

Can I use adopt on a project that was already initialized with init?

No — adopt exits with an error if logos/logos.config.json already exists. If you initialized with init and want to switch to launched lifecycle, run openlogos launch instead.

What does bootstrap: adopted actually do?

It tells OpenLogos that this project skipped the initial document baseline. The effects:

• openlogos status shows Phase 1–3 as ⏭️ (skipped) instead of ❌ (missing)
• openlogos next suggests creating a change directly (openlogos change <slug>) instead of “write requirements”
• openlogos launch doesn’t require Phase 1–3 docs to be present

My test command is complex — how do I configure it?

Edit logos/logos.config.json directly:

{
  "verify": {
    "result_path": "logos/resources/verify/test-results.jsonl",
    "pre_run_command": "docker compose up -d && npm test && docker compose down"
  }
}

---

Next steps

• CLI Reference: adopt — Full command reference with all options
• Change Management — How the Delta workflow works in detail
• Test Results Format — Reporter templates for all major test frameworks
• First AI Collaboration — End-to-end walkthrough of a full feature cycle