Skip to the content.

Clike HOWTO

Developer-first reminder

In CLike, the developer has the primary role in validating every phase and refining generated documents.

If alignment with the requirements is still weak, the developer can progressively add more detail to the requirement or source material so the process becomes more efficient as the work advances.

This document explains the recommended step-by-step operational flow to start and drive a project with CLike and the Harper process.

It is written as a practical onboarding guide and is meant to be linked from the main README.md.


Why this HOWTO matters

A good HOWTO should do more than explain commands.
It should help a developer become operational quickly, confidently, and with the right mindset.

For CLike, that mindset is simple:

The example used in this guide is a new project called:


The Operating Principle

CLike is not a passive content generator.
It is a developer-led orchestration workflow.

The developer remains responsible for:

The best way to use Harper in practice is:

  1. generate the artifact
  2. read it critically
  3. refine it where needed
  4. approve it by moving to the next phase

That makes the workflow both efficient and controlled.


Prerequisites

Before you start, make sure you already have:

If you want to use the agentic local execution path, also make sure you have:

Recommended preparation:


End-to-End Flow at a Glance

/init β†’ read README_1st.md β†’ configure git β†’ /idea β†’ review IDEA.md
β†’ /spec β†’ review SPEC.md
β†’ /plan β†’ review PLAN.md and plan.json
β†’ (/kit β†’ /eval [--fix] β†’ /gate [--fix]) repeated for each REQ-ID
β†’ /finalize
β†’ next release: /idea --extend β†’ (/kit β†’ /eval β†’ /gate) for the new REQs β†’ /finalize

The first phases define intent and structure. The middle loop delivers the actual solution requirement by requirement. The final phase closes the work and prepares the project for final documentation and pull request material.


Step 1 β€” Initialize the Project

Create or register the project workspace with CLike.

Command

/init CoffeeBuddy

Optional folder override:

/init CoffeeBuddy ./coffeebuddy

What this does

Developer checkpoint

Before doing anything else, verify that:

A wrong /init poisons everything that follows.


Step 2 β€” Read README_1st.md

Before generating any Harper artifact, read the bootstrap document if it exists.

What to look for

Why it matters

This is the fastest way to avoid generating documents that are beautifully written but badly grounded.

Developer checkpoint

If something important is missing, unclear, or implicit, note it immediately before moving on.


Step 3 β€” Configure Git

Before entering the generation flow, make sure Git is in a healthy state.

Typical checks

git status
git branch
git remote -v

If needed:

git init
git add .
git commit -m "chore: initial workspace setup"

What β€œgood” looks like

Developer checkpoint

Do not start the Harper flow on top of a vague or unstable repository situation.


Step 4 β€” Generate IDEA.md

Create the initial Harper idea document starting from an attached source file.

Command

/idea

What to attach

Attach the file that best represents the initial project intent, for example:

Instead of attaching, you can put the source documents in docs/inputs/ (requirements) and docs/reference/ (background): the phases read them as context sources (see context-sources.md).

Model and execution selection

At this stage select:

For /idea, the usual recommendation is Auto or Cloud Only.

Objective

Generate an IDEA.md that is coherent with the Harper process and captures:

Developer checkpoint

Read IDEA.md carefully.

Ask:

If not, refine the input or the generated document before moving on.


Step 5 β€” Generate SPEC.md

Once IDEA.md is acceptable, generate the specification.

Command

/spec

Model and execution selection

At this stage select:

Objective

Generate a Markdown specification that turns intent into a testable contract.

Typical contents include:

Developer checkpoint

Read SPEC.md like a demanding reviewer.

Validate that:

If alignment is weak, enrich the requirement now. This is one of the highest-leverage moments in the whole flow.


Step 6 β€” Generate PLAN.md and plan.json

Convert the specification into an executable plan.

Command

/plan

Objective

Generate:

What these artifacts should contain

Expected result

You should now have requirement identifiers such as:

Developer checkpoint

Review both PLAN.md and plan.json.

Ask:

A sharp plan makes /kit dramatically more effective.

πŸ‘‰ Read how to extend PLAN for new REQs CLike_Harper_Extend_Feature.md


Step 7 β€” Build a Requirement with /kit

Start implementation for a specific requirement.

Example command

/kit REQ-001

This phase supports two execution scenarios.


Scenario A β€” Agentic path

Use the local-agent path when you want implementation to be executed through Claude Code or GPT Codex.

First select the default local agent

/agent-default codex

or

/agent-default claude

or

/agent-default auto

Then choose execution mode

Use one of:

Prerequisites

You must already have installed at least one supported local agent:

What happens here

Best when


Scenario B β€” Cloud path

Use the cloud path when you want /kit to run without local agent execution.

Execution mode

Select:

What happens here

Best when


/kit is not just one shot

The implementation flow is iterative. Depending on project setup, /kit may involve internal follow-up phases such as:

These phases help improve promotability before final promotion.

Developer checkpoint

Before moving to /eval, review what /kit produced.

Validate:

If the output is only partially aligned, sharpen the requirement details and re-run the loop. This is where good developers quietly save hours.


Step 8 β€” Execute /eval

Run the validation phase after /kit.

Command

/eval

Purpose

This phase runs the REQ’s eval profile (ci/LTC.json) in the CLike eval sandbox and confirms that the generated implementation behaves correctly. It also re-runs the checks of the REQs already promoted (regression).

/eval REQ-001 --fix ["hint"] turns a failing eval into a governed repair loop: the code is repaired from the real failures, the tests stay locked (see auto-eval.md).

Typical checks include:

Completion condition

The phase is successful when the required checks complete with acceptable results.

Developer checkpoint

Review the evidence like someone who will own the output later.

Do not proceed if:


Step 9 β€” Execute /gate

Once the validation results are acceptable, use /gate to verify or promote the requirement.

Two common paths are available.

Path A β€” Manual promotion after successful manual verification

/gate REQ-001 manual pass

Use this when:

This is an audited override: CLike asks for a reason and reports OVERRIDE, never PASS.

Path B β€” Standard gate verification

/gate REQ-001

Use this when:

A passing gate promotes the REQ into src/ and test/ by auto-merge, without prompts, and writes a promotion report (conflicting files are never written: see git-and-promotion.md). /gate REQ-001 --fix ["hint"] repairs a failing gate like /eval --fix.

Developer checkpoint

The developer remains the final validator of whether the requirement is actually acceptable for progression or promotion.

If needed, go back, refine the requirement, and rerun the loop.


Step 10 β€” Repeat for All REQ-IDs

Steps 7, 8, and 9 are iterative.

Repeat them for each requirement:

/kit REQ-002
/eval
/gate REQ-002
/kit REQ-003
/eval
/gate REQ-003

Continue until all planned requirements are implemented and validated.

Developer checkpoint

As the project advances, keep improving precision where needed. Small requirement refinements at the right time usually produce outsized gains later.


Step 11 β€” Finalize the Solution

Once all REQ-IDs are completed, run the final closing step.

Command

/finalize

Purpose

This phase finalizes the documentation and prepares the delivery artifacts, then verifies that the integrated solution installs, builds, configures, starts and answers (it does not run the REQs’ tests again: each gate did) and repairs it while it fails (clike.finalize.verify).

Typical outputs may include:

Developer checkpoint

Before considering the work complete, perform one last serious review of the full documentation set and confirm that the final result matches the intended solution.


Step 12 β€” The Next Release

A delivered project evolves by releases. Put the requirements of the next release in docs/inputs/v2/ (background in docs/reference/v2/) β€” no attachment needed; attached files add to them, and an attachment is required only when docs/inputs/v2/ is empty β€” then:

/idea --extend [--from attachment] [--release v2] [--dry-run]

CLike merges the release into IDEA.md, SPEC.md and TECH_CONSTRAINTS.yaml, appends new REQs typed ADDED / MODIFIED / REMOVED to the plan (delivered REQs stay read-only), writes an EXTEND report with a CLike verification section, and tags the delivered baseline harper/v1. Review the report, then run the loop of steps 7–9 on the new REQs and /finalize at the end of the release. /extend remains the plan-only way to append REQs.


Practical Example for CoffeeBuddy

A minimal example sequence:

/init CoffeeBuddy
/idea
/spec
/plan
/agent-default auto
/kit REQ-001
/eval
/gate REQ-001
/kit REQ-002
/eval
/gate REQ-002
/finalize

If you prefer cloud-only execution for build:

/init CoffeeBuddy
/idea
/spec
/plan
/kit REQ-001
/eval
/gate REQ-001
/finalize

In that case, set execution mode to Cloud Only before running /kit.


Smart Operating Advice


Troubleshooting Notes

/kit does not use the local agent as expected

Check:

/idea or /spec produce weak output

Check:

/gate does not promote the requirement

Check:


Summary

For a new project such as CoffeeBuddy, the recommended operational journey is:

  1. initialize the project
  2. read the bootstrap docs
  3. prepare Git
  4. generate IDEA.md
  5. review and refine IDEA.md
  6. generate SPEC.md
  7. review and refine SPEC.md
  8. generate PLAN.md and plan.json
  9. review and refine planning artifacts
  10. implement each REQ with /kit
  11. validate with /eval
  12. promote or verify with /gate
  13. repeat until all REQs are complete
  14. close with /finalize
  15. evolve the delivered project with /idea --extend for the next release

Final Reminder β€” Developer-Centered Approach

The Harper flow in CLike works best when the developer stays fully engaged as:

Remember these operating principles:

This is not a passive generation flow. It is a developer-led orchestration workflow supported by CLike.

Approach reminder

The developer remains the orchestrator and approver of every phase. If output alignment is weak, enrich the requirement or source material with sharper details before proceeding.