ci/opencode/ci/workflows/init.md

description

description
Initialize a new CIAgent project — specification → clarify → create .ciagent/ reference files → initial commit

CIAgent Init

Initialize a new CIAgent project with specification parsing, clarification, and .ciagent/ reference file creation.

Usage: ciagent-init [description]

Step 0: Confirm Active Project

Check ci listProjects() or read .ciagent/config.json to determine if multi-project mode is active.

If .ciagent/config.json has projects[] with length > 0:

• Confirm active_project is correct for this initialization
• If not, set it with ci setActiveProject(<slug>)
• All subsequent operations use .ciagent/<slug>/ subdirectories
• All commit messages must include project: <slug> in ---ci--- block

If single-project mode: proceed with existing conventions.

Step 1: Check Prerequisites

Verify git is initialized:

[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"

If NO_GIT: git init

Check if .ciagent/config.json already exists:

[ -f .ciagent/config.json ] && echo "ALREADY_INITIALIZED" || echo "NEW"

If ALREADY_INITIALIZED: stop. Use ciagent-status to see project state.

Step 2: Parse Specification

If a description was provided, use it as the project specification. Otherwise, ask:

"What is the project specification? Describe the objective, requirements, constraints, and out-of-scope items."

Extract from the specification:

• Objective (what the project builds)
• Requirements (what it must do)
• Constraints (what it must not do or must use)
• Out of scope (what is explicitly excluded)

Step 3: Clarify

Analyze the specification for ambiguities. For each ambiguity:

1. Generate a clarify question with default answer
2. If autonomy level is full: accept defaults automatically
3. If autonomy level is supervised or guided: present question, wait for answer
4. Log all clarification decisions

Record decisions in the ---ci--- block of the init commit.

Step 4: Create .ciagent/ Files

Use CiFiles to create the project structure:

1. .ciagent/config.json — registry with projects[] and active_project
2. .ciagent/<slug>/PROJECT.md — vision, requirements, constraints, key decisions (or .ciagent/PROJECT.md in single-project mode)
3. .ciagent/<slug>/ARCHITECTURE.md — system architecture (initial, may be incomplete)
4. .ciagent/<slug>/ROADMAP.md — phase breakdown (to be refined by roadmapper)
5. .ciagent/<slug>/REQUIREMENTS.md — formal requirements with REQ-IDs

initCI() accepts projectSlug and projectName parameters for multi-project initialization.

Step 5: Create Initial Branches

git checkout -b milestone/v1.0-initial

Step 6: Initial Commit

docs(init): initialize [project-name] ([N] phases)

---ci---
project: <slug>
phase: 0
milestone: v1.0
status: specify
decisions:
  - id: D-001
    decision: [clarification decision]
    rationale: [why]
    confidence: 0.XX
    alternatives: []
---/ci---

Specification: [objective]
Requirements: [req1, req2, ...]
Constraints: [constraint1, ...]
Out of scope: [item1, ...]

Include project: <slug> in the ---ci--- block when in multi-project mode.

Step 7: Done

Report project initialized, .ciagent/ files created, initial branch created.

Next: ciagent-run to execute the pipeline, or ciagent-quick for ad-hoc tasks.