hanarang-rails/docs/migration-guide.md

Migration Guide

How to move from an existing agent pipeline (e.g., a Lobster-based hanarang-harness install) to hanarang-rails.

Summary

hanarang-rails replaces the legacy "권고 기반" pipeline with a deterministic, contract-enforced one. The migration is safe: nothing in the archive is deleted, and rails can run side-by-side until you cut over.

Before you start

• Back up the old install. Keep the archive read-only; don't delete it.
• Install rails on a neutral host — ideally the same machine that holds the SSOT repository, not one of the agent workers.
• Confirm Node 22+ and pnpm are available via rails doctor.

Step 0 — Install rails

bash install.sh --dir /path/to/hanarang-rails --repo <your-rails-repo-url>
cd /path/to/hanarang-rails
cp .env.example .env   # fill DATABASE_URL, DISCORD_TOKEN, etc.
pnpm prisma migrate deploy
pnpm rails doctor

Step 1 — Scan the archive

rails migrate from-hanarang-harness /path/to/hanarang-harness-archive

This reports:

• Agents (md files) — candidates to port
• Scripts — portable vs deprecated (bridge.sh is deprecated)
• Workflows — Lobster files are flagged as deprecated
• Warnings — e.g., any xhigh thinking tier reference (forbidden)

No files are modified. Review the report and decide.

Step 2 — Bring over agent definitions

Copy the agent markdown files you want to keep into the rails agents/ directory. Rails does not prescribe a naming scheme; rails.config.yaml maps stage → agent, so you can keep role-specific personas.

mkdir -p agents/
cp /path/to/archive/agents/*.md agents/

Review each file and remove anything that references:

• xhigh thinking tier (forbidden in rails — causes infinite waits)
• Mention-based handoff instructions
• Direct discord bot behavior (rails now posts on their behalf)

Step 3 — Port scaffolding

The legacy scaffold.sh is now rails scaffold:

rails scaffold /path/to/new-project --name my-project

This creates .plans/ with the standard directory structure (design/, sprints/, migration/) plus a root Plans.md.

Step 4 — Wire rails.config.yaml

pipeline:
  stages: [plan, implement, review, deploy]

agents:
  plan:
    role: plan
    displayName: Planner
    transport: discord
    channelId: ${PLAN_CHANNEL}
    timeoutMs: 30000
  implement:
    role: implement
    displayName: Generator
    transport: discord
    channelId: ${IMPL_CHANNEL}
    timeoutMs: 60000
  review:
    role: review
    displayName: Evaluator
    transport: discord
    channelId: ${REVIEW_CHANNEL}
    timeoutMs: 30000
  deploy:
    role: deploy
    displayName: Deploy
    transport: local
    timeoutMs: 60000

discord:
  enabled: true
  railsToken: ${RAILS_DISCORD_TOKEN}
  guildId: ${DISCORD_GUILD_ID}
  pipelineChannelId: ${PIPELINE_THREAD_PARENT}

All secrets live in .env. The config file uses ${VAR} interpolation — no token bytes in the repo.

Step 5 — Update agent runtimes

Each agent host (e.g., a sister container) needs one change to its message handler:

// Pseudocode — plug into your agent's discord event handler
onDiscordMessage(msg) {
  if (msg.content.includes("<!-- rails:invoke v1 -->")) {
    const req = extractJsonBlock(msg.content, "rails:invoke");
    // Structured pipeline mode — LLM 우회
    const result = await handleRailsInvoke(req);
    await postResultMarker(msg.channel, result);
    return;
  }
  // Otherwise: existing free-form conversation path
  llmRespond(msg);
}

See docs/discord-setup.md for the full marker format.

Step 6 — Cutover

1. Smoke test with mock transport first:

   rails run --mock test-project -r "hello world"
   rails status
   

   This exercises the full FSM without touching real agents.

2. Switch one stage at a time to discord:

   agents:
     plan:
       transport: discord  # flip this first
     implement:
       transport: mock     # keep others on mock until plan is green
   

3. Monitor escalations:

   rails status <pipeline-id>
   

   Any unexpected escalation triggers discord alert (if configured).

4. Disable legacy mention-based handoff on the old agents once all stages run through rails.

Step 7 — Decommission legacy bridge

After rails handles 100% of traffic:

1. Stop the old bridge.sh process(es).
2. Keep the archive as read-only reference.
3. Remove any cron jobs or systemd units that referenced the old install.

Rollback

If rails fails badly:

rails abort <pipeline-id>              # stop the misbehaving pipeline
pm2 stop hanarang-rails                # stop the orchestrator
# Start the legacy bridge again if it's still present

The SSOT repository is untouched — both systems write to the same Gitea.

Known limitations (v0.1.0)

• Discord bot wiring requires an operator task. Rails ships the DiscordTransport class but does not auto-connect discord.js; you plug in a client via the DiscordPoster interface. A default implementation will ship in v0.2.0.
• Gitea webhook receiver is scaffolded but not yet exposed as an HTTP endpoint in rails serve — tracked for v0.2.0.
• Manual QA checks are stubbed (SKIPPED by default). Provide a manualResolver to runQaTemplate to wire up a reviewer LLM.

Further reading

• .plans/failure-audit.md — why rails exists (F1–F6)
• .plans/design/ — architecture docs
• docs/operations.md — day-to-day operations guide