flight-rules 0.13.9 → 0.15.0

package/README.md

@@ -110,6 +110,8 @@ Flight Rules provides workflow commands that agents can execute:
 | `/prd.reconcile` | Update PRD based on what was actually built |
 | `/impl.reconcile` | Update implementation docs with status changes |
 | `/docs.reconcile` | Run all reconcile commands + consistency check |
+| `/parallel.status` | Show all active parallel sessions |
+| `/parallel.cleanup` | Clean up orphaned parallel sessions |
 
 ### Versioning
 
@@ -199,6 +201,63 @@ your-project/
 | `flight-rules adapter` | Generate agent-specific adapters (`--cursor`, `--claude`) |
 | `flight-rules update` | Update the Flight Rules CLI itself (`--channel` to switch dev/latest) |
 | `flight-rules ralph` | Run autonomous agent loop through task groups |
+| `flight-rules parallel` | Manage parallel dev sessions with git worktrees |
+
+---
+
+## Parallel Dev Sessions
+
+Flight Rules supports running multiple AI agents on the same project simultaneously using **git worktrees**. Each parallel session gets its own isolated directory and branch, so agents don't interfere with each other.
+
+### How It Works
+
+1. **Create a session** — `flight-rules parallel create <name>` creates a new worktree in a sibling directory (`../<project>-sessions/<name>/`) with a dedicated `session/<name>` branch
+2. **Work in isolation** — Open a new terminal, `cd` into the worktree, and run your AI agent. All file changes happen in the isolated directory
+3. **Track sessions** — `flight-rules parallel status` shows all active sessions, their branches, and ages
+4. **Integrate changes** — When done, `flight-rules parallel remove <name>` offers merge strategies: create a PR, merge directly, keep the branch, or abandon
+5. **Clean up** — `flight-rules parallel cleanup` detects orphaned sessions (e.g., from crashed terminals) and removes them
+
+### Session Directory Layout
+
+```
+/my-project                    ← main working directory
+/my-project-sessions/          ← parallel session worktrees
+  ├── auth-refactor/           ← Session A's worktree
+  ├── api-endpoints/           ← Session B's worktree
+  └── .manifest.json           ← tracks active sessions
+```
+
+### Commands
+
+```bash
+# Create a new parallel session
+flight-rules parallel create auth-refactor
+
+# See all active sessions
+flight-rules parallel status
+
+# End a session (offers merge workflow)
+flight-rules parallel remove auth-refactor
+
+# Clean up orphaned sessions
+flight-rules parallel cleanup
+
+# Skip confirmations
+flight-rules parallel cleanup --force
+flight-rules parallel remove auth-refactor --force
+```
+
+### Integration with Dev Sessions
+
+The `/dev-session.start` command offers a parallel session option after establishing goals. When ending a session in a worktree, `/dev-session.end` automatically offers the merge workflow.
+
+### Features
+
+- **Session manifest** — JSON file tracking all active sessions with metadata
+- **Env file copying** — Automatically copies `.env`, `.env.local`, `.env.development.local` to new worktrees
+- **Orphan detection** — Detects sessions where the worktree was removed without proper cleanup
+- **Merge conflict awareness** — Warns when the base branch has diverged since the session started
+- **Worktree validation** — Prevents creating nested parallel sessions
 
 ---
 
@@ -365,6 +424,7 @@ Tests are located in `tests/` and mirror the `src/` structure:
 | `tests/commands/init.test.ts` | 98.5% |
 | `tests/commands/upgrade.test.ts` | 100% |
 | `tests/commands/adapter.test.ts` | 79% |
+| `tests/commands/parallel.test.ts` | New |
 
 ### Releasing
 

package/dist/commands/init.js

@@ -15,6 +15,7 @@ async function copyDocsFromTemplates(templatesDir, docsDir, skipExisting) {
     ensureDir(docsDir);
     ensureDir(join(docsDir, 'implementation'));
     ensureDir(join(docsDir, 'session_logs'));
+    ensureDir(join(docsDir, 'backlog'));
     for (const file of DOC_FILES) {
         const srcPath = join(templatesDir, file.src);
         const destPath = join(docsDir, file.dest);

package/dist/commands/parallel.d.ts

@@ -0,0 +1,104 @@
+export interface SessionEntry {
+    id: string;
+    branch: string;
+    worktree: string;
+    startedAt: string;
+    goals: string[];
+    status: 'active' | 'completed' | 'abandoned';
+}
+export interface SessionManifest {
+    version: number;
+    project: string;
+    sessions: SessionEntry[];
+}
+export interface ParallelOptions {
+    force?: boolean;
+}
+/**
+ * Run a git command and return the result
+ */
+export declare function runGitCommand(args: string[], cwd?: string): Promise<{
+    success: boolean;
+    output: string;
+    error: string;
+}>;
+/**
+ * Check if git working directory is clean
+ */
+export declare function isGitClean(cwd?: string): Promise<boolean>;
+/**
+ * Check if the current directory is inside a git worktree (not the main working tree)
+ */
+export declare function isInsideWorktree(cwd?: string): Promise<boolean>;
+/**
+ * Get list of git worktrees
+ */
+export declare function listGitWorktrees(cwd?: string): Promise<Array<{
+    path: string;
+    branch: string;
+    bare: boolean;
+}>>;
+/**
+ * Get the number of commits the base branch is ahead of the session branch point
+ */
+export declare function getCommitsAhead(baseBranch: string, sessionBranch: string, cwd?: string): Promise<number>;
+/**
+ * Get the current branch name
+ */
+export declare function getCurrentBranch(cwd?: string): Promise<string>;
+/**
+ * Get the sessions directory path for a project
+ */
+export declare function getSessionsDir(projectDir: string): string;
+/**
+ * Get the manifest file path
+ */
+export declare function getManifestPath(projectDir: string): string;
+/**
+ * Read the session manifest, returning null if not found or invalid
+ */
+export declare function readSessionManifest(projectDir: string): SessionManifest | null;
+/**
+ * Write the session manifest
+ */
+export declare function writeSessionManifest(projectDir: string, manifest: SessionManifest): void;
+/**
+ * Create an empty manifest for a project
+ */
+export declare function createEmptyManifest(projectDir: string): SessionManifest;
+/**
+ * Add a session to the manifest
+ */
+export declare function addSessionToManifest(projectDir: string, session: SessionEntry): SessionManifest;
+/**
+ * Remove a session from the manifest by ID
+ */
+export declare function removeSessionFromManifest(projectDir: string, sessionId: string): SessionManifest | null;
+/**
+ * Copy common environment files from source to destination
+ */
+export declare function copyEnvFiles(sourceDir: string, destDir: string): string[];
+/**
+ * Format a relative time string from an ISO date
+ */
+export declare function formatRelativeTime(isoDate: string): string;
+/**
+ * Create a new parallel session
+ */
+export declare function parallelCreate(sessionName: string, goals?: string[]): Promise<void>;
+/**
+ * Show status of all parallel sessions
+ */
+export declare function parallelStatus(): Promise<void>;
+/**
+ * Clean up orphaned parallel sessions
+ */
+export declare function parallelCleanup(options?: ParallelOptions): Promise<void>;
+/**
+ * Remove a specific parallel session with merge workflow
+ */
+export declare function parallelRemove(sessionName: string, options?: ParallelOptions): Promise<void>;
+/**
+ * Main parallel command dispatcher
+ */
+export declare function parallel(subcommand: string, args: string[], options?: ParallelOptions): Promise<void>;