Claude-Code-Workflow/.claude/commands/workflow/session/solidify.md

name, description, argument-hint, examples

name	description	argument-hint	examples
solidify	Crystallize session learnings and user-defined constraints into permanent project guidelines	[-y|--yes] [--type <convention|constraint|learning>] [--category <category>] "rule or insight"	/workflow:session:solidify "Use functional components for all React code" --type convention /workflow:session:solidify -y "No direct DB access from controllers" --type constraint --category architecture /workflow:session:solidify "Cache invalidation requires event sourcing" --type learning --category architecture /workflow:session:solidify --interactive

Auto Mode

When --yes or -y: Auto-categorize and add guideline without confirmation.

Session Solidify Command (/workflow:session:solidify)

Overview

Crystallizes ephemeral session context (insights, decisions, constraints) into permanent project guidelines stored in .workflow/project-guidelines.json. This ensures valuable learnings persist across sessions and inform future planning.

Use Cases

1. During Session: Capture important decisions as they're made
2. After Session: Reflect on lessons learned before archiving
3. Proactive: Add team conventions or architectural rules

Parameters

Parameter	Type	Required	Description
rule	string	✅ (unless --interactive)	The rule, convention, or insight to solidify
--type	enum	❌	Type: convention, constraint, learning (default: auto-detect)
--category	string	❌	Category for organization (see categories below)
--interactive	flag	❌	Launch guided wizard for adding rules

Type Categories

convention → Coding style preferences (goes to conventions section)

• Subcategories: coding_style, naming_patterns, file_structure, documentation

constraint → Hard rules that must not be violated (goes to constraints section)

• Subcategories: architecture, tech_stack, performance, security

learning → Session-specific insights (goes to learnings array)

• Subcategories: architecture, performance, security, testing, process, other

Execution Process

Input Parsing:
   ├─ Parse: rule text (required unless --interactive)
   ├─ Parse: --type (convention|constraint|learning)
   ├─ Parse: --category (subcategory)
   └─ Parse: --interactive (flag)

Step 1: Ensure Guidelines File Exists
   └─ If not exists → Create with empty structure

Step 2: Auto-detect Type (if not specified)
   └─ Analyze rule text for keywords

Step 3: Validate and Format Entry
   └─ Build entry object based on type

Step 4: Update Guidelines File
   └─ Add entry to appropriate section

Step 5: Display Confirmation
   └─ Show what was added and where

Implementation

Step 1: Ensure Guidelines File Exists

bash(test -f .workflow/project-guidelines.json && echo "EXISTS" || echo "NOT_FOUND")

If NOT_FOUND, create scaffold:

const scaffold = {
  conventions: {
    coding_style: [],
    naming_patterns: [],
    file_structure: [],
    documentation: []
  },
  constraints: {
    architecture: [],
    tech_stack: [],
    performance: [],
    security: []
  },
  quality_rules: [],
  learnings: [],
  _metadata: {
    created_at: new Date().toISOString(),
    version: "1.0.0"
  }
};

Write('.workflow/project-guidelines.json', JSON.stringify(scaffold, null, 2));

Step 2: Auto-detect Type (if not specified)

function detectType(ruleText) {
  const text = ruleText.toLowerCase();

  // Constraint indicators
  if (/\b(no|never|must not|forbidden|prohibited|always must)\b/.test(text)) {
    return 'constraint';
  }

  // Learning indicators
  if (/\b(learned|discovered|realized|found that|turns out)\b/.test(text)) {
    return 'learning';
  }

  // Default to convention
  return 'convention';
}

function detectCategory(ruleText, type) {
  const text = ruleText.toLowerCase();

  if (type === 'constraint' || type === 'learning') {
    if (/\b(architecture|layer|module|dependency|circular)\b/.test(text)) return 'architecture';
    if (/\b(security|auth|permission|sanitize|xss|sql)\b/.test(text)) return 'security';
    if (/\b(performance|cache|lazy|async|sync|slow)\b/.test(text)) return 'performance';
    if (/\b(test|coverage|mock|stub)\b/.test(text)) return 'testing';
  }

  if (type === 'convention') {
    if (/\b(name|naming|prefix|suffix|camel|pascal)\b/.test(text)) return 'naming_patterns';
    if (/\b(file|folder|directory|structure|organize)\b/.test(text)) return 'file_structure';
    if (/\b(doc|comment|jsdoc|readme)\b/.test(text)) return 'documentation';
    return 'coding_style';
  }

  return type === 'constraint' ? 'tech_stack' : 'other';
}

Step 3: Build Entry

function buildEntry(rule, type, category, sessionId) {
  if (type === 'learning') {
    return {
      date: new Date().toISOString().split('T')[0],
      session_id: sessionId || null,
      insight: rule,
      category: category,
      context: null
    };
  }

  // For conventions and constraints, just return the rule string
  return rule;
}

Step 4: Update Guidelines File

const guidelines = JSON.parse(Read('.workflow/project-guidelines.json'));

if (type === 'convention') {
  if (!guidelines.conventions[category]) {
    guidelines.conventions[category] = [];
  }
  if (!guidelines.conventions[category].includes(rule)) {
    guidelines.conventions[category].push(rule);
  }
} else if (type === 'constraint') {
  if (!guidelines.constraints[category]) {
    guidelines.constraints[category] = [];
  }
  if (!guidelines.constraints[category].includes(rule)) {
    guidelines.constraints[category].push(rule);
  }
} else if (type === 'learning') {
  guidelines.learnings.push(buildEntry(rule, type, category, sessionId));
}

guidelines._metadata.updated_at = new Date().toISOString();
guidelines._metadata.last_solidified_by = sessionId;

Write('.workflow/project-guidelines.json', JSON.stringify(guidelines, null, 2));

Step 5: Display Confirmation

✓ Guideline solidified

Type: ${type}
Category: ${category}
Rule: "${rule}"

Location: .workflow/project-guidelines.json → ${type}s.${category}

Total ${type}s in ${category}: ${count}

Interactive Mode

When --interactive flag is provided:

AskUserQuestion({
  questions: [
    {
      question: "What type of guideline are you adding?",
      header: "Type",
      multiSelect: false,
      options: [
        { label: "Convention", description: "Coding style preference (e.g., use functional components)" },
        { label: "Constraint", description: "Hard rule that must not be violated (e.g., no direct DB access)" },
        { label: "Learning", description: "Insight from this session (e.g., cache invalidation needs events)" }
      ]
    }
  ]
});

// Follow-up based on type selection...

Examples

Add a Convention

/workflow:session:solidify "Use async/await instead of callbacks" --type convention --category coding_style

Result in project-guidelines.json:

{
  "conventions": {
    "coding_style": ["Use async/await instead of callbacks"]
  }
}

Add an Architectural Constraint

/workflow:session:solidify "No direct DB access from controllers" --type constraint --category architecture

Result:

{
  "constraints": {
    "architecture": ["No direct DB access from controllers"]
  }
}

Capture a Session Learning

/workflow:session:solidify "Cache invalidation requires event sourcing for consistency" --type learning

Result:

{
  "learnings": [
    {
      "date": "2024-12-28",
      "session_id": "WFS-auth-feature",
      "insight": "Cache invalidation requires event sourcing for consistency",
      "category": "architecture"
    }
  ]
}

Integration with Planning

The project-guidelines.json is consumed by:

1. /workflow:tools:context-gather: Loads guidelines into context-package.json
2. /workflow:plan: Passes guidelines to task generation agent
3. task-generate-agent: Includes guidelines as "CRITICAL CONSTRAINTS" in system prompt

This ensures all future planning respects solidified rules without users needing to re-state them.

Error Handling

• Duplicate Rule: Warn and skip if exact rule already exists
• Invalid Category: Suggest valid categories for the type
• File Corruption: Backup existing file before modification

Related Commands

• /workflow:session:start - Start a session (may prompt for solidify at end)
• /workflow:session:complete - Complete session (prompts for learnings to solidify)
• /workflow:init - Creates project-guidelines.json scaffold if missing