@forwardimpact/pathway 0.1.0 → 0.2.0

package/app/model/agent.js

@@ -104,8 +104,9 @@ export function toKebabCase(id) {
 /**
  * Derive agent skills using the unified profile system
  * Returns skills sorted by level (highest first) for the given discipline × track
- * Excludes human-only skills (those requiring human presence/experience)
- * Excludes broad skills unless they're in a capability with positive track modifier
+ * Excludes human-only skills and keeps only skills at the highest derived level.
+ * This approach respects track modifiers—a broad skill boosted to the same level
+ * as primary skills will be included.
  * @param {Object} params - Parameters
  * @param {Object} params.discipline - Human discipline definition
  * @param {Object} params.track - Human track definition
@@ -123,7 +124,7 @@ export function deriveAgentSkills({ discipline, track, grade, skills }) {
   });
 
   // Apply agent-specific filtering and sorting
-  const filtered = filterSkillsForAgent(skillMatrix, track);
+  const filtered = filterSkillsForAgent(skillMatrix);
   return sortByLevelDescending(filtered);
 }
 
@@ -224,28 +225,110 @@ function buildWorkingStyleFromBehaviours(
   return sections.join("\n");
 }
 
+/**
+ * Stage ID to display name and next stage mapping
+ */
+const STAGE_INFO = {
+  plan: { name: "Plan", nextStage: "Code" },
+  code: { name: "Code", nextStage: "Review" },
+  review: { name: "Review", nextStage: "Complete" },
+};
+
 /**
  * Generate SKILL.md content from skill data
- * @param {Object} skillData - Skill with agent section
- * @returns {Object} Skill with frontmatter, body, and dirname
+ * @param {Object} skillData - Skill with agent section containing stages
+ * @returns {Object} Skill with frontmatter, title, stages array, reference, dirname
  */
 export function generateSkillMd(skillData) {
-  const { agent } = skillData;
+  const { agent, name } = skillData;
 
   if (!agent) {
     throw new Error(`Skill ${skillData.id} has no agent section`);
   }
 
+  if (!agent.stages) {
+    throw new Error(`Skill ${skillData.id} agent section missing stages`);
+  }
+
+  // Transform stages object to array for template rendering
+  const stagesArray = Object.entries(agent.stages).map(
+    ([stageId, stageData]) => {
+      const info = STAGE_INFO[stageId] || {
+        name: stageId,
+        nextStage: "Next",
+      };
+      return {
+        stageId,
+        stageName: info.name,
+        nextStageName: info.nextStage,
+        focus: stageData.focus,
+        activities: stageData.activities || [],
+        ready: stageData.ready || [],
+      };
+    },
+  );
+
+  // Sort stages in order: plan, code, review
+  const stageOrder = ["plan", "code", "review"];
+  stagesArray.sort(
+    (a, b) => stageOrder.indexOf(a.stageId) - stageOrder.indexOf(b.stageId),
+  );
+
   return {
     frontmatter: {
       name: agent.name,
       description: agent.description.trim(),
     },
-    body: agent.body.trim(),
+    title: name,
+    stages: stagesArray,
+    reference: agent.reference ? agent.reference.trim() : "",
     dirname: agent.name,
   };
 }
 
+/**
+ * Estimate total character length of bodyData fields
+ * @param {Object} bodyData - Structured profile body data
+ * @returns {number} Estimated character count
+ */
+function estimateBodyDataLength(bodyData) {
+  let length = 0;
+
+  // String fields
+  const stringFields = [
+    "title",
+    "stageDescription",
+    "identity",
+    "priority",
+    "delegation",
+    "operationalContext",
+    "workingStyle",
+    "beforeHandoff",
+  ];
+  for (const field of stringFields) {
+    if (bodyData[field]) {
+      length += bodyData[field].length;
+    }
+  }
+
+  // Array fields
+  if (bodyData.capabilities) {
+    length += bodyData.capabilities.join(", ").length;
+  }
+  if (bodyData.beforeMakingChanges) {
+    for (const item of bodyData.beforeMakingChanges) {
+      length += item.text.length + 5; // +5 for "1. " prefix
+    }
+  }
+  if (bodyData.constraints) {
+    for (const c of bodyData.constraints) {
+      length += c.length + 2; // +2 for "- " prefix
+    }
+  }
+
+  return length;
+}
+
 /**
  * Validate agent profile against spec constraints
  * @param {Object} profile - Generated profile
@@ -266,9 +349,10 @@ export function validateAgentProfile(profile) {
     }
   }
 
-  // Body length limit (30,000 chars)
-  if (profile.body.length > 30000) {
-    errors.push(`Body exceeds 30,000 character limit (${profile.body.length})`);
+  // Body length limit (30,000 chars) - estimate from bodyData fields
+  const bodyLength = estimateBodyDataLength(profile.bodyData);
+  if (bodyLength > 30000) {
+    errors.push(`Body exceeds 30,000 character limit (${bodyLength})`);
   }
 
   // Tools format
@@ -322,17 +406,6 @@ export function validateAgentSkill(skill) {
 // Stage-Based Agent Generation
 // =============================================================================
 
-/**
- * Derive tools for a stage-based agent
- * Stages define the authoritative tool set for each lifecycle phase
- * @param {Object} params - Parameters
- * @param {Object} params.stage - Stage definition from stages.yaml
- * @returns {string[]} Array of tool names
- */
-export function deriveAgentTools({ stage }) {
-  return stage.availableTools || [];
-}
-
 /**
  * Derive handoff buttons for a stage-based agent
  * Generates handoff button definitions from stage.handoffs with rich prompts
@@ -349,8 +422,9 @@ export function deriveHandoffs({ stage, discipline, track, stages }) {
     return [];
   }
 
-  // Build base name for target agents
-  const baseName = `${toKebabCase(discipline.id)}-${toKebabCase(track.id)}`;
+  // Build base name for target agents (matches filename without .agent.md)
+  const abbrev = getDisciplineAbbreviation(discipline.id);
+  const baseName = `${abbrev}-${toKebabCase(track.id)}`;
 
   return stage.handoffs.map((handoff) => {
     // Find the target stage to get its entry criteria
@@ -390,19 +464,16 @@ export function deriveHandoffs({ stage, discipline, track, stages }) {
 /**
  * Get the handoff type for a stage (used for checklist derivation)
  * @param {string} stageId - Stage ID (plan, code, review)
- * @returns {string|null} Handoff type or null
+ * @returns {string|null} Stage ID for checklist or null
  */
-function getHandoffForStage(stageId) {
-  const handoffMap = {
-    plan: "plan_to_code",
-    code: "code_to_review",
-    review: null, // Review stage doesn't need a checklist
-  };
-  return handoffMap[stageId] || null;
+function getChecklistStage(stageId) {
+  // Plan and code stages have checklists, review doesn't
+  return stageId === "review" ? null : stageId;
 }
 
 /**
- * Build the profile body for a stage-based agent
+ * Build the profile body data for a stage-based agent
+ * Returns structured data for template rendering
  * @param {Object} params - Parameters
  * @param {Object} params.stage - Stage definition
  * @param {Object} params.humanDiscipline - Human discipline definition
@@ -413,9 +484,9 @@ function getHandoffForStage(stageId) {
  * @param {Array} params.derivedBehaviours - Behaviours sorted by maturity
  * @param {Array} params.agentBehaviours - Agent behaviour definitions
  * @param {string} params.checklistMarkdown - Pre-formatted checklist markdown
- * @returns {string} Profile body markdown
+ * @returns {Object} Structured profile body data
  */
-function buildStageProfileBody({
+function buildStageProfileBodyData({
   stage,
   humanDiscipline,
   humanTrack,
@@ -428,103 +499,64 @@ function buildStageProfileBody({
 }) {
   const name = `${humanDiscipline.specialization || humanDiscipline.name} - ${humanTrack.name}`;
   const stageName = stage.name.charAt(0).toUpperCase() + stage.name.slice(1);
-  const sections = [];
-
-  // Title with stage indicator
-  sections.push(`# ${name} - ${stageName} Agent`);
-  sections.push("");
 
-  // Stage description
-  sections.push(stage.description);
-  sections.push("");
-
-  // Core Identity
-  sections.push("## Core Identity");
-  sections.push("");
-
-  // Use track coreInstructions if available, with template substitution
-  const rawInstructions =
-    agentTrack.coreInstructions || agentDiscipline.coreInstructions;
-  const coreInstructions = substituteTemplateVars(
-    rawInstructions,
-    humanDiscipline,
-  );
-  sections.push(coreInstructions.trim());
-  sections.push("");
+  // Build identity - prefer track, fall back to discipline
+  const rawIdentity = agentTrack.identity || agentDiscipline.identity;
+  const identity = substituteTemplateVars(rawIdentity, humanDiscipline);
+
+  // Build priority - prefer track, fall back to discipline (optional)
+  const rawPriority = agentTrack.priority || agentDiscipline.priority;
+  const priority = rawPriority
+    ? substituteTemplateVars(rawPriority, humanDiscipline)
+    : null;
+
+  // Build beforeMakingChanges list - prefer track, fall back to discipline
+  const rawSteps =
+    agentTrack.beforeMakingChanges || agentDiscipline.beforeMakingChanges || [];
+  const beforeMakingChanges = rawSteps.map((text, i) => ({
+    index: i + 1,
+    text: substituteTemplateVars(text, humanDiscipline),
+  }));
+
+  // Delegation (from discipline only, optional)
+  const rawDelegation = agentDiscipline.delegation;
+  const delegation = rawDelegation
+    ? substituteTemplateVars(rawDelegation, humanDiscipline)
+    : null;
 
   // Primary capabilities from derived skills
-  const topSkills = derivedSkills.slice(0, 6);
-  if (topSkills.length > 0) {
-    sections.push("Your primary capabilities:");
-    for (const skill of topSkills) {
-      sections.push(`- ${skill.skillName}`);
-    }
-    sections.push("");
-  }
+  const capabilities = derivedSkills.slice(0, 6).map((s) => s.skillName);
 
   // Operational Context - use track's roleContext (shared with human job descriptions)
-  sections.push("## Operational Context");
-  sections.push("");
-  sections.push(humanTrack.roleContext.trim());
-  sections.push("");
+  const operationalContext = humanTrack.roleContext.trim();
 
-  // Working Style from derived behaviours
+  // Working Style from derived behaviours (still markdown for now)
   const workingStyle = buildWorkingStyleFromBehaviours(
     derivedBehaviours,
     agentBehaviours,
     3,
   );
-  sections.push(workingStyle);
-
-  // Before Handoff (if provided)
-  if (checklistMarkdown) {
-    sections.push("## Before Handoff");
-    sections.push("");
-    sections.push(
-      "Before offering a handoff, verify and summarize completion of these items:",
-    );
-    sections.push("");
-    sections.push(checklistMarkdown);
-    sections.push("");
-    sections.push(
-      "When verified, summarize what was accomplished then offer the handoff.",
-    );
-    sections.push("If items are incomplete, explain what remains.");
-    sections.push("");
-  }
-
-  // Return Format section
-  sections.push("## Return Format");
-  sections.push("");
-  sections.push(
-    "When completing work (for handoff or as a subagent), provide:",
-  );
-  sections.push("");
-  sections.push("1. **Work completed**: What was accomplished");
-  sections.push(
-    "2. **Checklist status**: Items verified from Before Handoff section",
-  );
-  sections.push(
-    "3. **Recommendation**: Ready for next stage, or needs more work",
-  );
-  sections.push("");
 
   // Constraints (stage + discipline + track)
-  const allConstraints = [
+  const constraints = [
     ...(stage.constraints || []),
     ...(agentDiscipline.constraints || []),
     ...(agentTrack.constraints || []),
   ];
-  if (allConstraints.length > 0) {
-    sections.push("## Constraints");
-    sections.push("");
-    for (const constraint of allConstraints) {
-      sections.push(`- ${constraint}`);
-    }
-    sections.push("");
-  }
 
-  return sections.join("\n");
+  return {
+    title: `${name} - ${stageName} Agent`,
+    stageDescription: stage.description,
+    identity: identity.trim(),
+    priority: priority ? priority.trim() : null,
+    capabilities,
+    beforeMakingChanges,
+    delegation: delegation ? delegation.trim() : null,
+    operationalContext,
+    workingStyle,
+    beforeHandoff: checklistMarkdown || null,
+    constraints,
+  };
 }
 
 /**
@@ -540,7 +572,7 @@ function buildStageProfileBody({
  * @param {Array} params.agentBehaviours - Agent behaviour definitions
  * @param {Object} params.agentDiscipline - Agent discipline definition
  * @param {Object} params.agentTrack - Agent track definition
- * @param {Array} params.capabilities - Capabilities with checklists
+ * @param {Array} params.capabilities - Capabilities for checklist grouping
  * @param {Array} params.stages - All stages (for handoff entry criteria)
  * @returns {Object} Agent definition with skills, behaviours, tools, handoffs, constraints, checklist
  */
@@ -572,9 +604,6 @@ export function deriveStageAgent({
     behaviours,
   });
 
-  // Derive tools from stage
-  const tools = deriveAgentTools({ stage });
-
   // Derive handoffs from stage
   const handoffs = deriveHandoffs({
     stage,
@@ -584,12 +613,13 @@ export function deriveStageAgent({
   });
 
   // Derive checklist if applicable
-  const handoffType = getHandoffForStage(stage.id);
+  const checklistStage = getChecklistStage(stage.id);
   let checklist = [];
-  if (handoffType && capabilities) {
+  if (checklistStage && capabilities) {
     checklist = deriveChecklist({
-      handoff: handoffType,
+      stageId: checklistStage,
       skillMatrix: derivedSkills,
+      skills,
       capabilities,
     });
   }
@@ -600,7 +630,6 @@ export function deriveStageAgent({
     track,
     derivedSkills,
     derivedBehaviours,
-    tools,
     handoffs,
     constraints: [
       ...(stage.constraints || []),
@@ -616,7 +645,7 @@ export function deriveStageAgent({
 
 /**
  * Generate a stage-specific agent profile (.agent.md)
- * Produces the complete profile with frontmatter, body, and filename
+ * Produces the complete profile with frontmatter, bodyData, and filename
  * @param {Object} params - Parameters
  * @param {Object} params.discipline - Human discipline definition
  * @param {Object} params.track - Human track definition
@@ -629,7 +658,7 @@ export function deriveStageAgent({
  * @param {Object} params.agentTrack - Agent track definition
  * @param {Array} params.capabilities - Capabilities with checklists
  * @param {Array} params.stages - All stages (for handoff entry criteria)
- * @returns {Object} Profile with frontmatter, body, and filename
+ * @returns {Object} Profile with frontmatter, bodyData, and filename
  */
 export function generateStageAgentProfile({
   discipline,
@@ -659,10 +688,10 @@ export function generateStageAgentProfile({
     stages,
   });
 
-  // Build names
-  const fullName = `${toKebabCase(discipline.id)}-${toKebabCase(track.id)}-${stage.id}`;
+  // Build names (abbreviated form used consistently for filename, name, and handoffs)
   const abbrev = getDisciplineAbbreviation(discipline.id);
-  const filename = `${abbrev}-${toKebabCase(track.id)}-${stage.id}.agent.md`;
+  const fullName = `${abbrev}-${toKebabCase(track.id)}-${stage.id}`;
+  const filename = `${fullName}.agent.md`;
 
   // Build description
   const disciplineDesc = discipline.description.trim().split("\n")[0];
@@ -672,8 +701,8 @@ export function generateStageAgentProfile({
   // Format checklist as markdown
   const checklistMarkdown = formatChecklistMarkdown(agent.checklist);
 
-  // Build profile body
-  const body = buildStageProfileBody({
+  // Build structured profile body data
+  const bodyData = buildStageProfileBodyData({
     stage,
     humanDiscipline: discipline,
     humanTrack: track,
@@ -689,14 +718,13 @@ export function generateStageAgentProfile({
   const frontmatter = {
     name: fullName,
     description,
-    tools: agent.tools,
     infer: true,
     ...(agent.handoffs.length > 0 && { handoffs: agent.handoffs }),
   };
 
   return {
     frontmatter,
-    body,
+    bodyData,
     filename,
   };
 }

package/app/model/checklist.js

@@ -1,116 +1,81 @@
 /**
  * Checklist Derivation
  *
- * Checklists are derived from:
- * Checklist = Handoff × Skills Matrix × Capability Checklists
+ * Checklists are derived from skills with agent.stages.{stage}.ready criteria.
+ * Each skill defines its own readiness criteria for stage transitions.
  *
- * The skill matrix determines which capability levels are relevant,
- * and the capability checklists provide items for each level.
+ * Checklist = Stage × Skill Matrix × Skill Ready Criteria
  */
 
-import { SKILL_LEVEL_ORDER, getSkillLevelIndex } from "./levels.js";
-
 /**
- * Get the maximum skill level for a capability from the skill matrix
- * @param {Array} skillMatrix - Derived skill matrix with entries like { skillId, level, capability }
- * @param {string} capabilityId - Capability ID to check
- * @returns {string|null} Maximum skill level or null if no skills in this capability
+ * Map from stage ID to the stage whose ready criteria should be shown
+ * (i.e., what must be ready before leaving this stage)
  */
-export function getMaxCapabilityLevel(skillMatrix, capabilityId) {
-  const skillsInCapability = skillMatrix.filter(
-    (entry) => entry.capability === capabilityId,
-  );
-
-  if (skillsInCapability.length === 0) {
-    return null;
-  }
-
-  // Find the highest level among skills in this capability
-  let maxIndex = -1;
-  let maxLevel = null;
-
-  for (const entry of skillsInCapability) {
-    const index = getSkillLevelIndex(entry.level);
-    if (index > maxIndex) {
-      maxIndex = index;
-      maxLevel = entry.level;
-    }
-  }
-
-  return maxLevel;
-}
+const STAGE_TO_HANDOFF = {
+  plan: "plan", // Show plan.ready before leaving plan
+  code: "code", // Show code.ready before leaving code
+  review: "review", // Show review.ready (completion criteria)
+};
 
 /**
- * Get all checklist items up to and including a given level
- * @param {Object} checklists - Capability checklists for a specific handoff
- * @param {string} maxLevel - Maximum level to include
- * @returns {string[]} Array of checklist items
+ * Derive checklist items for a specific stage
+ * Returns skills grouped by capability with their ready criteria
+ *
+ * @param {Object} params
+ * @param {string} params.stageId - Current stage (plan, code, review)
+ * @param {Array} params.skillMatrix - Derived skill matrix with skill details
+ * @param {Array} params.skills - All skills (to look up agent.stages)
+ * @param {Array} params.capabilities - All capabilities (for emoji lookup)
+ * @returns {Array<{skill: Object, capability: Object, items: string[]}>} Checklist items grouped by skill
  */
-function getChecklistItemsUpToLevel(checklists, maxLevel) {
-  if (!checklists || !maxLevel) {
+export function deriveChecklist({
+  stageId,
+  skillMatrix,
+  skills,
+  capabilities,
+}) {
+  const targetStage = STAGE_TO_HANDOFF[stageId];
+  if (!targetStage) {
     return [];
   }
 
-  const maxIndex = getSkillLevelIndex(maxLevel);
-  const items = [];
+  // Build skill lookup
+  const skillById = new Map(skills.map((s) => [s.id, s]));
 
-  // Include items from all levels up to and including maxLevel
-  for (const level of SKILL_LEVEL_ORDER) {
-    const levelIndex = getSkillLevelIndex(level);
-    if (levelIndex <= maxIndex && checklists[level]) {
-      items.push(...checklists[level]);
-    }
-  }
-
-  return items;
-}
+  // Build capability lookup
+  const capabilityById = new Map(capabilities.map((c) => [c.id, c]));
 
-/**
- * Derive checklist items for a specific handoff
- *
- * @param {Object} params
- * @param {string} params.handoff - Handoff type (plan_to_code, code_to_review)
- * @param {Array} params.skillMatrix - Derived skill matrix
- * @param {Array} params.capabilities - All capabilities with checklists
- * @returns {Array<{capability: Object, level: string, items: string[]}>} Checklist items grouped by capability
- */
-export function deriveChecklist({ handoff, skillMatrix, capabilities }) {
   const result = [];
 
-  for (const capability of capabilities) {
-    // Skip if no checklists defined for this capability
-    if (
-      !capability.transitionChecklists ||
-      !capability.transitionChecklists[handoff]
-    ) {
+  for (const entry of skillMatrix) {
+    const skill = skillById.get(entry.skillId);
+    if (!skill || !skill.agent || !skill.agent.stages) {
       continue;
     }
 
-    // Find the max skill level for this capability
-    const maxLevel = getMaxCapabilityLevel(skillMatrix, capability.id);
-
-    // Skip awareness level - not ready for checklists
-    if (!maxLevel || maxLevel === "awareness") {
+    const stageData = skill.agent.stages[targetStage];
+    if (!stageData || !stageData.ready || stageData.ready.length === 0) {
       continue;
     }
 
-    // Get all items up to the max level
-    const items = getChecklistItemsUpToLevel(
-      capability.transitionChecklists[handoff],
-      maxLevel,
-    );
-
-    if (items.length > 0) {
-      result.push({
-        capability: {
-          id: capability.id,
-          name: capability.name,
-          emoji: capability.emoji,
-        },
-        level: maxLevel,
-        items,
-      });
+    // Get capability for this skill
+    const capability = capabilityById.get(entry.capability);
+    if (!capability) {
+      continue;
     }
+
+    result.push({
+      skill: {
+        id: skill.id,
+        name: skill.name,
+      },
+      capability: {
+        id: capability.id,
+        name: capability.name,
+        emoji: capability.emoji,
+      },
+      items: stageData.ready,
+    });
   }
 
   return result;
@@ -118,8 +83,9 @@ export function deriveChecklist({ handoff, skillMatrix, capabilities }) {
 
 /**
  * Format a checklist for display (markdown format)
+ * Groups items by skill with capability emoji
  *
- * @param {Array<{capability: Object, level: string, items: string[]}>} checklist - Derived checklist
+ * @param {Array<{skill: Object, capability: Object, items: string[]}>} checklist - Derived checklist
  * @returns {string} Markdown-formatted checklist
  */
 export function formatChecklistMarkdown(checklist) {
@@ -127,8 +93,8 @@ export function formatChecklistMarkdown(checklist) {
     return "";
   }
 
-  const sections = checklist.map(({ capability, items }) => {
-    const header = `**${capability.emoji} ${capability.name}**`;
+  const sections = checklist.map(({ skill, capability, items }) => {
+    const header = `**${capability.emoji} ${skill.name}**`;
     const itemList = items.map((item) => `- [ ] ${item}`).join("\n");
     return `${header}\n\n${itemList}`;
   });