sequant 1.20.1 → 1.20.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases",
-  "version": "1.20.1",
+  "version": "1.20.2",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/dist/bin/cli.js

@@ -82,6 +82,7 @@ program
     .option("-i, --interactive", "Force interactive mode even in non-TTY environment")
     .option("--skip-setup", "Skip the dependency setup wizard")
     .option("--no-symlinks", "Use copies instead of symlinks for scripts/dev/ files")
+    .option("--no-agents-md", "Skip AGENTS.md generation")
     .action(initCommand);
 program
     .command("update")
@@ -165,6 +166,7 @@ program
     .description("View and manage codebase conventions")
     .option("--detect", "Re-run convention detection")
     .option("--reset", "Clear detected conventions (keep manual)")
+    .option("--format <format>", "Output format (agents-md for AGENTS.md format)")
     .action(conventionsCommand);
 program
     .command("logs")

package/dist/src/commands/conventions.d.ts

@@ -4,6 +4,7 @@
 interface ConventionsOptions {
     detect?: boolean;
     reset?: boolean;
+    format?: string;
 }
 export declare function conventionsCommand(options: ConventionsOptions): Promise<void>;
 export {};

package/dist/src/commands/conventions.js

@@ -4,6 +4,7 @@
 import chalk from "chalk";
 import { detectAndSaveConventions, loadConventions, formatConventions, CONVENTIONS_PATH, } from "../lib/conventions-detector.js";
 import { fileExists, writeFile } from "../lib/fs.js";
+import { formatConventionsAsAgentsMd } from "../lib/agents-md.js";
 export async function conventionsCommand(options) {
     if (options.reset) {
         await handleReset();
@@ -13,6 +14,10 @@ export async function conventionsCommand(options) {
         await handleDetect();
         return;
     }
+    if (options.format === "agents-md") {
+        await handleFormatAgentsMd();
+        return;
+    }
     // Default: show current conventions
     await handleShow();
 }
@@ -45,6 +50,15 @@ async function handleReset() {
         }
     }
 }
+async function handleFormatAgentsMd() {
+    const conventions = await loadConventions();
+    if (!conventions) {
+        console.log(chalk.yellow("No conventions detected yet."));
+        console.log(chalk.gray("Run 'sequant conventions --detect' first to detect conventions."));
+        return;
+    }
+    console.log(formatConventionsAsAgentsMd(conventions));
+}
 async function handleShow() {
     if (!(await fileExists(CONVENTIONS_PATH))) {
         console.log(chalk.yellow("No conventions detected yet."));

package/dist/src/commands/doctor.js

@@ -9,6 +9,8 @@ import { getManifest } from "../lib/manifest.js";
 import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, getMcpServersConfig, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
 import { checkVersionThorough, getVersionWarning, } from "../lib/version-check.js";
 import { areSkillsOutdated } from "./sync.js";
+import { readAgentsMd, checkAgentsMdConsistency, AGENTS_MD_PATH, } from "../lib/agents-md.js";
+import { readFile } from "../lib/fs.js";
 /**
  * Labels that indicate an issue should be skipped from closed-issue verification
  * (case-insensitive matching)
@@ -174,6 +176,52 @@ export async function doctorCommand(options = {}) {
             message: `Up to date (${skillsStatus.packageVersion})`,
         });
     }
+    // Check: AGENTS.md presence and consistency
+    const agentsMdContent = await readAgentsMd();
+    if (agentsMdContent) {
+        // Check consistency with CLAUDE.md if both exist
+        if (await fileExists("CLAUDE.md")) {
+            try {
+                const claudeMdContent = await readFile("CLAUDE.md");
+                const inconsistency = checkAgentsMdConsistency(agentsMdContent, claudeMdContent);
+                if (inconsistency) {
+                    checks.push({
+                        name: "AGENTS.md",
+                        status: "warn",
+                        message: `Out of sync with CLAUDE.md: ${inconsistency}. Run: sequant sync --force`,
+                    });
+                }
+                else {
+                    checks.push({
+                        name: "AGENTS.md",
+                        status: "pass",
+                        message: "Present and consistent with CLAUDE.md",
+                    });
+                }
+            }
+            catch {
+                checks.push({
+                    name: "AGENTS.md",
+                    status: "pass",
+                    message: "Present (could not verify consistency)",
+                });
+            }
+        }
+        else {
+            checks.push({
+                name: "AGENTS.md",
+                status: "pass",
+                message: "Present",
+            });
+        }
+    }
+    else if (manifest) {
+        checks.push({
+            name: "AGENTS.md",
+            status: "warn",
+            message: `Missing ${AGENTS_MD_PATH} - run: sequant init --force (or sequant sync --force)`,
+        });
+    }
     // Check 4: Hooks directory
     const hooksExist = await fileExists(".claude/hooks");
     if (hooksExist) {

package/dist/src/commands/init.d.ts

@@ -8,6 +8,7 @@ interface InitOptions {
     interactive?: boolean;
     skipSetup?: boolean;
     noSymlinks?: boolean;
+    agentsMd?: boolean;
 }
 export declare function initCommand(options: InitOptions): Promise<void>;
 export {};

package/dist/src/commands/init.js

@@ -11,6 +11,7 @@ import { saveConfig } from "../lib/config.js";
 import { createDefaultSettings } from "../lib/settings.js";
 import { detectAndSaveConventions } from "../lib/conventions-detector.js";
 import { fileExists, ensureDir, readFile, writeFile } from "../lib/fs.js";
+import { generateAgentsMd, writeAgentsMd } from "../lib/agents-md.js";
 import { commandExists, isGhAuthenticated, getInstallHint, } from "../lib/system.js";
 import { shouldUseInteractiveMode, getNonInteractiveReason, } from "../lib/tty.js";
 import { checkAllDependencies, displayDependencyStatus, runSetupWizard, shouldRunSetupWizard, } from "../lib/wizard.js";
@@ -289,6 +290,9 @@ export async function initCommand(options) {
     console.log(chalk.gray("  └── logs/           (workflow run logs)"));
     console.log(chalk.gray("  scripts/dev/"));
     console.log(chalk.gray("  └── *.sh            (worktree helpers)"));
+    if (options.agentsMd !== false) {
+        console.log(chalk.gray("  AGENTS.md           (universal agent instructions)"));
+    }
     if (!skipPrompts) {
         const { confirm } = await inquirer.prompt([
             {
@@ -394,6 +398,31 @@ export async function initCommand(options) {
     manifestSpinner.start();
     await createManifest(stack, packageManager ?? undefined);
     manifestSpinner.succeed("Created manifest");
+    // Generate AGENTS.md (unless --no-agents-md)
+    if (options.agentsMd !== false) {
+        const agentsSpinner = ui.spinner("Generating AGENTS.md...");
+        agentsSpinner.start();
+        try {
+            const stackConfig = getStackConfig(stack);
+            const { getProjectName } = await import("../lib/project-name.js");
+            const projectName = await getProjectName();
+            const agentsMdContent = await generateAgentsMd({
+                projectName,
+                stack: stack,
+                buildCommand: stackConfig.variables.BUILD_COMMAND,
+                testCommand: stackConfig.variables.TEST_COMMAND,
+                lintCommand: stackConfig.variables.LINT_COMMAND,
+            });
+            await writeAgentsMd(agentsMdContent);
+            agentsSpinner.succeed("Generated AGENTS.md");
+        }
+        catch {
+            agentsSpinner.warn("Could not generate AGENTS.md (non-blocking)");
+        }
+    }
+    else {
+        console.log(chalk.gray("Skipping AGENTS.md generation (--no-agents-md)"));
+    }
     // Build optional suggestions section
     const optionalSuggestions = suggestions.filter((s) => s.startsWith("Optional"));
     const optionalSection = optionalSuggestions.length > 0

package/dist/src/commands/sync.js

@@ -9,6 +9,9 @@ import { getManifest, updateManifest, getPackageVersion, } from "../lib/manifest
 import { copyTemplates } from "../lib/templates.js";
 import { getConfig } from "../lib/config.js";
 import { writeFile, readFile, fileExists } from "../lib/fs.js";
+import { generateAgentsMd, writeAgentsMd, AGENTS_MD_PATH, } from "../lib/agents-md.js";
+import { getProjectName } from "../lib/project-name.js";
+import { getStackConfig } from "../lib/stacks.js";
 const SKILLS_VERSION_PATH = ".claude/skills/.sequant-version";
 /**
  * Get the version of skills currently installed
@@ -86,6 +89,29 @@ export async function syncCommand(options = {}) {
     // Update version markers
     await updateSkillsVersion();
     await updateManifest();
+    // Regenerate AGENTS.md if it exists
+    if (await fileExists(AGENTS_MD_PATH)) {
+        try {
+            const stackConfig = getStackConfig(manifest.stack);
+            const projectName = await getProjectName();
+            const agentsMdContent = await generateAgentsMd({
+                projectName,
+                stack: manifest.stack,
+                buildCommand: stackConfig.variables.BUILD_COMMAND,
+                testCommand: stackConfig.variables.TEST_COMMAND,
+                lintCommand: stackConfig.variables.LINT_COMMAND,
+            });
+            await writeAgentsMd(agentsMdContent);
+            if (!quiet) {
+                console.log(chalk.blue("📄 Regenerated AGENTS.md"));
+            }
+        }
+        catch {
+            if (!quiet) {
+                console.log(chalk.yellow("⚠️  Could not regenerate AGENTS.md (non-blocking)"));
+            }
+        }
+    }
     if (!quiet) {
         console.log(chalk.green(`\n✅ Synced to v${packageVersion}`));
         console.log(chalk.gray("\nSkills, hooks, and memory files have been updated."));

package/dist/src/lib/agents-md.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AGENTS.md generation and management
+ *
+ * Generates a universal AGENTS.md file that any AI coding agent can consume.
+ * AGENTS.md contains the portable subset of CLAUDE.md instructions.
+ */
+import { type ConventionsFile } from "./conventions-detector.js";
+/** Path to AGENTS.md in project root */
+export declare const AGENTS_MD_PATH = "AGENTS.md";
+/** Configuration for generating AGENTS.md */
+export interface AgentsMdConfig {
+    projectName: string;
+    stack: string;
+    buildCommand?: string;
+    testCommand?: string;
+    lintCommand?: string;
+}
+/**
+ * Generate AGENTS.md content from project configuration
+ */
+export declare function generateAgentsMd(config: AgentsMdConfig): Promise<string>;
+/**
+ * Extract portable (non-Claude-specific) instructions from CLAUDE.md
+ */
+export declare function extractPortableInstructions(claudeMdContent: string): string;
+/**
+ * Check if AGENTS.md is consistent with CLAUDE.md content.
+ * Returns a description of inconsistencies, or null if consistent.
+ */
+export declare function checkAgentsMdConsistency(agentsMdContent: string, claudeMdContent: string): string | null;
+/**
+ * Format conventions for AGENTS.md output
+ */
+export declare function formatConventionsAsAgentsMd(conventions: ConventionsFile): string;
+/**
+ * Write AGENTS.md to the project root
+ */
+export declare function writeAgentsMd(content: string): Promise<void>;
+/**
+ * Read existing AGENTS.md if present
+ */
+export declare function readAgentsMd(): Promise<string | null>;

package/dist/src/lib/agents-md.js

@@ -0,0 +1,206 @@
+/**
+ * AGENTS.md generation and management
+ *
+ * Generates a universal AGENTS.md file that any AI coding agent can consume.
+ * AGENTS.md contains the portable subset of CLAUDE.md instructions.
+ */
+import { readFile, writeFile, fileExists } from "./fs.js";
+import { processTemplate } from "./templates.js";
+import { getStackConfig } from "./stacks.js";
+import { loadConventions, } from "./conventions-detector.js";
+/** Sections in CLAUDE.md that are Claude Code-specific and should NOT be ported */
+const CLAUDE_SPECIFIC_PATTERNS = [
+    /^##\s*Slash Commands/i,
+    /^##\s*Hook Configuration/i,
+    /^##\s*Hooks?$/i,
+    /^##\s*Claude Code/i,
+    /^##\s*MCP\b/i,
+    /^##\s*Skills?$/i,
+];
+/** Path to AGENTS.md in project root */
+export const AGENTS_MD_PATH = "AGENTS.md";
+/**
+ * The AGENTS.md template with {{TOKEN}} placeholders.
+ * Follows the standard format from https://github.com/agentsmd/agents.md
+ */
+const AGENTS_MD_TEMPLATE = `# AGENTS.md
+
+## Project Overview
+
+**{{PROJECT_NAME}}** is built with **{{STACK}}**.
+
+## Development Commands
+
+| Command | Purpose |
+|---------|---------|
+| \`{{BUILD_COMMAND}}\` | Build the project |
+| \`{{TEST_COMMAND}}\` | Run tests |
+| \`{{LINT_COMMAND}}\` | Lint the codebase |
+
+## Code Conventions
+
+{{CONVENTIONS_SECTION}}
+
+## Directory Structure
+
+Follow existing project conventions for file placement and naming.
+
+## Workflow
+
+This project uses [Sequant](https://github.com/sequant-io/sequant) for structured AI-assisted development.
+
+To work on a GitHub issue:
+
+\`\`\`bash
+npx sequant run <issue-number>
+\`\`\`
+
+This runs a structured workflow: spec → exec → qa.
+
+{{PORTABLE_INSTRUCTIONS}}
+`;
+/**
+ * Generate AGENTS.md content from project configuration
+ */
+export async function generateAgentsMd(config) {
+    const stackConfig = getStackConfig(config.stack);
+    const buildCmd = config.buildCommand ||
+        stackConfig.variables.BUILD_COMMAND ||
+        "npm run build";
+    const testCmd = config.testCommand || stackConfig.variables.TEST_COMMAND || "npm test";
+    const lintCmd = config.lintCommand || stackConfig.variables.LINT_COMMAND || "npm run lint";
+    // Load conventions if available
+    const conventionsSection = await getConventionsSection();
+    // Check for CLAUDE.md and extract portable instructions
+    const portableInstructions = await getPortableInstructions();
+    const variables = {
+        PROJECT_NAME: config.projectName,
+        STACK: stackConfig.displayName || config.stack,
+        BUILD_COMMAND: buildCmd,
+        TEST_COMMAND: testCmd,
+        LINT_COMMAND: lintCmd,
+        CONVENTIONS_SECTION: conventionsSection,
+        PORTABLE_INSTRUCTIONS: portableInstructions,
+    };
+    let content = processTemplate(AGENTS_MD_TEMPLATE, variables);
+    // Clean up empty sections
+    content = content.replace(/\n{3,}/g, "\n\n");
+    return content.trimEnd() + "\n";
+}
+/**
+ * Extract portable (non-Claude-specific) instructions from CLAUDE.md
+ */
+export function extractPortableInstructions(claudeMdContent) {
+    const lines = claudeMdContent.split("\n");
+    const portableLines = [];
+    let skipSection = false;
+    for (const line of lines) {
+        // Check if this line starts a Claude-specific section
+        if (line.startsWith("## ")) {
+            skipSection = CLAUDE_SPECIFIC_PATTERNS.some((pattern) => pattern.test(line));
+        }
+        if (!skipSection) {
+            portableLines.push(line);
+        }
+    }
+    const result = portableLines.join("\n").trim();
+    // Remove the top-level heading (e.g. "# Sequant") since AGENTS.md has its own
+    const withoutTopHeading = result.replace(/^#\s+.*\n*/, "").trim();
+    return withoutTopHeading;
+}
+/**
+ * Check if AGENTS.md is consistent with CLAUDE.md content.
+ * Returns a description of inconsistencies, or null if consistent.
+ */
+export function checkAgentsMdConsistency(agentsMdContent, claudeMdContent) {
+    const issues = [];
+    // Extract portable instructions from current CLAUDE.md
+    const portable = extractPortableInstructions(claudeMdContent);
+    // Check if key sections from CLAUDE.md portable content appear in AGENTS.md
+    // We check for commit rules and other conventions that should be shared
+    const commitRulePatterns = [/Co-Authored-By/i, /commit rules?/i];
+    for (const pattern of commitRulePatterns) {
+        const inClaude = pattern.test(portable);
+        const inAgents = pattern.test(agentsMdContent);
+        if (inClaude && !inAgents) {
+            issues.push(`CLAUDE.md contains "${pattern.source}" but AGENTS.md does not`);
+        }
+    }
+    return issues.length > 0 ? issues.join("; ") : null;
+}
+/**
+ * Format conventions for AGENTS.md output
+ */
+export function formatConventionsAsAgentsMd(conventions) {
+    const lines = ["# AGENTS.md", "", "## Code Conventions", ""];
+    const detected = Object.entries(conventions.detected);
+    const manual = Object.entries(conventions.manual);
+    const all = [...detected, ...manual];
+    if (all.length === 0) {
+        lines.push("No conventions detected.");
+    }
+    else {
+        for (const [key, value] of all) {
+            lines.push(`- **${key}**: ${value}`);
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+/**
+ * Write AGENTS.md to the project root
+ */
+export async function writeAgentsMd(content) {
+    await writeFile(AGENTS_MD_PATH, content);
+}
+/**
+ * Read existing AGENTS.md if present
+ */
+export async function readAgentsMd() {
+    if (!(await fileExists(AGENTS_MD_PATH))) {
+        return null;
+    }
+    try {
+        return await readFile(AGENTS_MD_PATH);
+    }
+    catch {
+        // File read failed — treat as missing (non-blocking)
+        return null;
+    }
+}
+// -- Internal helpers --
+async function getConventionsSection() {
+    try {
+        const conventions = await loadConventions();
+        if (!conventions)
+            return "Follow existing project patterns and naming conventions.";
+        const detected = Object.entries(conventions.detected);
+        const manual = Object.entries(conventions.manual);
+        const all = [...manual, ...detected]; // manual overrides first
+        if (all.length === 0)
+            return "Follow existing project patterns and naming conventions.";
+        const lines = [];
+        for (const [key, value] of all) {
+            lines.push(`- **${key}**: ${value}`);
+        }
+        return lines.join("\n");
+    }
+    catch {
+        // Convention loading failed — fall back to generic guidance (non-blocking)
+        return "Follow existing project patterns and naming conventions.";
+    }
+}
+async function getPortableInstructions() {
+    try {
+        if (!(await fileExists("CLAUDE.md")))
+            return "";
+        const claudeMd = await readFile("CLAUDE.md");
+        const portable = extractPortableInstructions(claudeMd);
+        if (!portable)
+            return "";
+        return `## Project-Specific Instructions\n\n${portable}`;
+    }
+    catch {
+        // CLAUDE.md read/parse failed — skip portable instructions (non-blocking)
+        return "";
+    }
+}

package/dist/src/lib/workflow/phase-executor.js

@@ -7,6 +7,7 @@
 import chalk from "chalk";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { getMcpServersConfig } from "../system.js";
+import { readAgentsMd } from "../agents-md.js";
 /**
  * Natural language prompts for each phase
  * These prompts will invoke the corresponding skills via natural language
@@ -21,10 +22,19 @@ const PHASE_PROMPTS = {
     loop: "Parse test/QA findings for GitHub issue #{issue} and iterate until quality gates pass. Run the /loop {issue} workflow.",
 };
 /**
- * Phases that require worktree isolation (exec, test, qa)
- * Spec runs in main repo since it's planning-only
+ * Phases that require worktree isolation.
+ * Spec runs in main repo since it's planning-only.
+ * security-review and loop must be isolated because they need to read/modify
+ * worktree code, and running them in main directory with a session created
+ * in the worktree causes the SDK to crash (cwd mismatch on session resume).
  */
-const ISOLATED_PHASES = ["exec", "test", "qa"];
+const ISOLATED_PHASES = [
+    "exec",
+    "security-review",
+    "test",
+    "qa",
+    "loop",
+];
 /**
  * Cold-start retry threshold in seconds.
  * Failures under this duration are likely Claude Code subprocess initialization
@@ -61,10 +71,20 @@ export function formatDuration(seconds) {
     return `${mins}m ${secs.toFixed(0)}s`;
 }
 /**
- * Get the prompt for a phase with the issue number substituted
+ * Get the prompt for a phase with the issue number substituted.
+ * Includes AGENTS.md content as context so non-Claude agents
+ * receive project conventions and workflow instructions.
  */
-function getPhasePrompt(phase, issueNumber) {
-    return PHASE_PROMPTS[phase].replace(/\{issue\}/g, String(issueNumber));
+async function getPhasePrompt(phase, issueNumber) {
+    const basePrompt = PHASE_PROMPTS[phase].replace(/\{issue\}/g, String(issueNumber));
+    // Include AGENTS.md content in the prompt context for non-Claude agent compatibility.
+    // Claude reads CLAUDE.md natively, but other agents (Aider, Codex, Gemini CLI)
+    // rely on AGENTS.md for project context.
+    const agentsMd = await readAgentsMd();
+    if (agentsMd) {
+        return `Project context (from AGENTS.md):\n\n${agentsMd}\n\n---\n\n${basePrompt}`;
+    }
+    return basePrompt;
 }
 /**
  * Execute a single phase for an issue using Claude Agent SDK
@@ -82,7 +102,7 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
             durationSeconds: 0,
         };
     }
-    const prompt = getPhasePrompt(phase, issueNumber);
+    const prompt = await getPhasePrompt(phase, issueNumber);
     if (config.verbose) {
         console.log(chalk.gray(`    Prompt: ${prompt}`));
         if (worktreePath && ISOLATED_PHASES.includes(phase)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.20.1",
+  "version": "1.20.2",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {