openlogos change
Scaffold a new change proposal directory with proposal.md, tasks.md, and deltas/ subdirectories, and record it as the active change in logos/.openlogos-guard. This is the entry point for the Delta workflow of a launched project.
Synopsis
Section titled “Synopsis”openlogos change <slug> [--module <id>]Must be run from the project root.
Arguments & options
Section titled “Arguments & options”| Argument / option | Required | Description |
|---|---|---|
slug | Yes | A kebab-case identifier for the change (e.g., fix-redirect-bug, add-remember-me) |
--module <id> | No | Assign the proposal to a module. With one module it is auto-assigned; with several it defaults to core; a multi-module project without core requires --module and prints one retry command per module. |
What it creates
Section titled “What it creates”logos/changes/<slug>/├── proposal.md # Change proposal template├── tasks.md # Task checklist ([delta] / [code] / [deploy])└── deltas/ ├── prd/ # Delta files for requirements / design / technical plan docs ├── api/ # Delta files for API specs ├── database/ # Delta files for DB schema └── scenario/ # Delta files for orchestration testsIt also writes logos/.openlogos-guard, which records the active change:
{ "activeChange": "fix-redirect-bug", "module": "core", "createdAt": "2026-10-12T08:00:00.000Z"}While the guard exists, the AI may change code and specs only within this proposal’s scope. Without it, a launched project’s version-controlled code and specs are protected (see PreToolUse guard).
Only one active proposal at a time
Section titled “Only one active proposal at a time”If the guard already points to a proposal that is still in logos/changes/ and not archived, change refuses to create a new one:
Error: Active change proposal 'add-remember-me' is still in progress.Finish it and explicitly request `openlogos archive add-remember-me` before creating a new proposal.A malformed guard file is also rejected; fix or remove it first. A slug that already exists in logos/changes/ is rejected too.
Generated templates
Section titled “Generated templates”proposal.md
Section titled “proposal.md”The template contains these sections (English headings for locale: en, Chinese for zh):
| Section | Purpose |
|---|---|
Reason | Why the change is needed |
Minimal Implementation Rationale | Optional self-check: what existing mechanisms were checked, why it can’t be smaller, what was cut |
Change Type | Requirements / Design / Interface / Code |
Scope | Affected requirements, feature specs, scenarios, APIs, DB tables, orchestration tests |
Deployment Impact | Whether deployment is needed and why, environments, data migration, rollback plan, smoke |
UI/UX Change Declaration | YAML block (ui_impact, design_system_mode, pages); meaningful for GUI projects |
Decision Clarification | openlogos/clarification@1 YAML block (see below) |
Summary | What will change, in 1–3 paragraphs |
Decision clarification (clarification@1)
Section titled “Decision clarification (clarification@1)”The Decision Clarification section records the choices that only a human can make — anything the repository, configuration or specs cannot answer. Its YAML block lists five kinds of impact, each with a status and a non-empty reason:
schema: openlogos/clarification@1mode: adaptivestatus: pendingimpacts: data: {status: none, reason: "..."} compatibility: {status: none, reason: "..."} security_privacy: {status: none, reason: "..."} public_release: {status: none, reason: "..."} external_commitment: {status: none, reason: "..."}decisions: []unresolved: []defaults: []nonemeans no user choice is needed (no impact, or facts / policy already decide it);requiredmeans a high-impact choice must be made by the user and recorded indecisions.- Deployment and public release are decided separately. Deployment comes from the
Deployment Impactsection;public_releasecovers npm publish, tags, releases or opening a website. Approving a local or production deployment does not approve a public release, and vice versa. - The section is required (change-lint L0 checks that it exists and is filled), but its content is a written record for people — it is not a hard gate and does not replace plan approval.
tasks.md
Section titled “tasks.md”For a launched module the template is:
# Implementation Tasks
## [delta] Spec Changes- [ ] Update requirements scenarios and acceptance criteria- [ ] Update product design feature specs
## [code] Code ImplementationThe [code] heading stays empty during planning — real [code] slices are written after merge by slice-planner through openlogos slice plan. A [deploy] section is added when the proposal needs deployment. See tasks.md Format.
Delivery gate: change-lint
Section titled “Delivery gate: change-lint”After filling proposal.md + tasks.md, and again after writing all deltas, run:
openlogos change-lintOnly exit 0 means the proposal artifacts are ready to hand over. openlogos merge uses the same verdict as its admission check, so fix violations here rather than at merge time. See openlogos change-lint.
Example output
Section titled “Example output”Creating change proposal: fix-redirect-bugModule: core (auto-detected, only one module registered)
✓ logos/changes/fix-redirect-bug/proposal.md ✓ logos/changes/fix-redirect-bug/tasks.md ✓ logos/changes/fix-redirect-bug/deltas/ ✓ logos/.openlogos-guard
Change proposal created. Next steps: 1. Tell AI: "Help me fill in change proposal fix-redirect-bug" 2. AI will analyze impact and fill in proposal.md + tasks.md 3. Then work through tasks.md, putting deltas in deltas/ 4. When done, explicitly request `openlogos merge fix-redirect-bug` …The Delta workflow
Section titled “The Delta workflow”openlogos change <slug> │ ▼ AI fills proposal.md + tasks.md → openlogos change-lint (exit 0) │ plan-exit: approve the plan ▼ AI writes deltas in deltas/ → openlogos change-lint (exit 0) │ spec-exit: review deltas, authorize merge ▼openlogos merge <slug> → one call, atomic; writes SPEC_MERGED │ ▼ slice-planner → openlogos slice plan → slice-exit: approve slices │ ▼ implement code + tests → openlogos verify (→ deploy → openlogos smoke) │ ▼openlogos archive <slug> → moves to archive/, removes the guardmerge, verify, deployment, smoke, archive and git push are human confirmation points unless you run openlogos next --auto.
Errors
Section titled “Errors”| Error | Cause | Fix |
|---|---|---|
Missing change proposal name | No slug provided | openlogos change add-remember-me |
Change proposal 'X' already exists | Same slug already in logos/changes/ | Choose another slug |
Active change proposal 'X' is still in progress | Another unarchived proposal holds the guard | Finish it and archive it first |
logos/.openlogos-guard is invalid | Guard file is not valid JSON | Fix or remove the guard file |
Module 'X' not found in logos-project.yaml | --module value is not registered | openlogos module list |
logos/logos.config.json not found | Not in project root | cd to project root |
Related commands
Section titled “Related commands”change-lint— Delivery gate for proposal and deltasmerge— Merge deltas once authorizedslice— Plan[code]slices after mergearchive— Archive the completed proposallaunch— Activate change management for a module