aigroup-workflow 2.1.2 → 2.2.1

package/scripts/orchestration/session.cjs

@@ -8,35 +8,52 @@ const {
   ROOT,
   sessionDir,
   workerArtifacts,
+  initSession,
   createWorker,
   updateStatus,
   appendHandoff,
+  completeHandoff,
+  refreshPlan,
+  buildPlan,
+  validateSession,
+  readJson,
   slugify,
   relPosix
 } = require('./lib/orchestrator.cjs');
 
-const COMMANDS = ['init', 'add-worker', 'status', 'set-status', 'append', 'list', 'help'];
+const COMMANDS = ['init', 'add-worker', 'status', 'set-status', 'append', 'complete', 'plan', 'validate', 'list', 'help'];
 
 function usage() {
   console.log([
     'Usage:',
-    '  node scripts/orchestration/session.js init <session-name>',
+    '  node scripts/orchestration/session.cjs init <session>',
     '  node scripts/orchestration/session.cjs add-worker <session> <worker> --agent <name> --objective <text>',
-    '                                                       [--context <line>]... [--deliverable <line>]... [--lightweight]',
-    '  node scripts/orchestration/session.js set-status <session> <worker> <state> [--details <text>]',
-    '  node scripts/orchestration/session.js append <session> <worker> <section> --content <text>',
-    '  node scripts/orchestration/session.js status <session>',
-    '  node scripts/orchestration/session.js list',
+    '                                                  [--context <line>]... [--deliverable <line>]...',
+    '                                                  [--depends-on <worker>]... [--lightweight]',
+    '  node scripts/orchestration/session.cjs set-status <session> <worker> <state> [--details <text>]',
+    '  node scripts/orchestration/session.cjs append <session> <worker> <section> --content <text>',
+    '  node scripts/orchestration/session.cjs complete <session> <worker>',
+    '                                                  [--summary <text>] [--validation <text>]',
+    '                                                  [--files <newline-or-comma-separated>]',
+    '                                                  [--follow-ups <newline-separated>]',
+    '                                                  [--stage-spec <text>] [--stage-quality <text>]',
+    '  node scripts/orchestration/session.cjs status <session>',
+    '  node scripts/orchestration/session.cjs plan <session>      # refresh and print plan.json',
+    '  node scripts/orchestration/session.cjs validate <session>  # validate all artifacts against schemas',
+    '  node scripts/orchestration/session.cjs list',
     '',
     'States: not_started | running | blocked | completed | failed',
-    `Coordination root: ${relPosix(COORDINATION_ROOT)}/`
+    `Coordination root: ${relPosix(COORDINATION_ROOT)}/`,
+    'Schemas:           schemas/orchestration/'
   ].join('\n'));
 }
 
 const BOOLEAN_FLAGS = new Set(['lightweight']);
+const REPEATABLE_FLAGS = new Set(['context', 'deliverable', 'depends-on']);
 
 function parseFlags(args) {
-  const flags = { context: [], deliverable: [] };
+  const flags = {};
+  for (const k of REPEATABLE_FLAGS) flags[k] = [];
   const positional = [];
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -47,7 +64,7 @@ function parseFlags(args) {
         continue;
       }
       const value = args[i + 1];
-      if (key === 'context' || key === 'deliverable') {
+      if (REPEATABLE_FLAGS.has(key)) {
         flags[key].push(value);
       } else {
         flags[key] = value;
@@ -61,17 +78,8 @@ function parseFlags(args) {
 }
 
 function cmdInit(name) {
-  if (!name) throw new Error('session-name is required');
-  const dir = sessionDir(name);
-  fs.mkdirSync(dir, { recursive: true });
-  const meta = path.join(dir, 'session.json');
-  if (!fs.existsSync(meta)) {
-    fs.writeFileSync(meta, JSON.stringify({
-      name: slugify(name, 'session'),
-      label: name,
-      createdAt: new Date().toISOString()
-    }, null, 2) + '\n', 'utf8');
-  }
+  if (!name) throw new Error('session name is required');
+  const dir = initSession(name);
   console.log(relPosix(dir));
 }
 
@@ -84,8 +92,9 @@ function cmdAddWorker(session, worker, flags) {
     workerName: worker,
     agent: flags.agent,
     objective: flags.objective,
-    context: flags.context,
-    deliverables: flags.deliverable,
+    context: flags.context || [],
+    deliverables: flags.deliverable || [],
+    dependsOn: flags['depends-on'] || [],
     lightweight: Boolean(flags.lightweight)
   });
   const out = {
@@ -110,23 +119,72 @@ function cmdAppend(session, worker, section, flags) {
   console.log(relPosix(file));
 }
 
+function cmdComplete(session, worker, flags) {
+  if (!session || !worker) throw new Error('session and worker names are required');
+  const fields = {};
+  if (flags.summary !== undefined) fields.summary = flags.summary;
+  if (flags.validation !== undefined) fields.validation = flags.validation;
+  if (flags.files !== undefined) fields.filesChanged = flags.files;
+  if (flags['follow-ups'] !== undefined) fields.followUps = flags['follow-ups'];
+  const stages = {};
+  if (flags['stage-spec'] !== undefined) stages.spec = flags['stage-spec'];
+  if (flags['stage-quality'] !== undefined) stages.quality = flags['stage-quality'];
+  if (Object.keys(stages).length > 0) fields.stages = stages;
+
+  if (Object.keys(fields).length === 0) {
+    throw new Error('at least one of --summary | --validation | --files | --follow-ups | --stage-spec | --stage-quality is required');
+  }
+  const file = completeHandoff(session, worker, fields);
+  console.log(relPosix(file));
+}
+
 function cmdStatus(session) {
-  if (!session) throw new Error('session-name is required');
+  if (!session) throw new Error('session name is required');
   const dir = sessionDir(session);
   if (!fs.existsSync(dir)) {
     console.log(`(no such session: ${session})`);
     return;
   }
-  const workers = fs.readdirSync(dir, { withFileTypes: true })
-    .filter(entry => entry.isDirectory())
-    .map(entry => entry.name);
-  const out = workers.map(worker => {
-    const statusPath = workerArtifacts(session, worker).status;
-    const content = fs.existsSync(statusPath) ? fs.readFileSync(statusPath, 'utf8') : '(missing)';
-    const stateLine = content.split('\n').find(line => line.startsWith('- State:'));
-    return `${worker}\t${stateLine ? stateLine.replace('- State:', '').trim() : '?'}`;
+  const plan = buildPlan(session);
+  if (plan.workers.length === 0) {
+    console.log('(no workers)');
+    return;
+  }
+  const lines = plan.workers.map(w => {
+    const lw = w.lightweight ? ' [lightweight]' : '';
+    const dep = w.dependsOn.length > 0 ? ` ⟵ ${w.dependsOn.join(',')}` : '';
+    return `${w.name}\t${w.state}${lw}${dep}`;
   });
-  console.log(out.join('\n') || '(no workers)');
+  console.log(lines.join('\n'));
+  console.log('');
+  console.log(`ready: ${plan.buckets.ready.join(', ') || '∅'}`);
+  console.log(`running: ${plan.buckets.running.join(', ') || '∅'}`);
+  console.log(`blocked: ${plan.buckets.blocked.join(', ') || '∅'}`);
+  console.log(`waiting: ${plan.buckets.waiting.join(', ') || '∅'}`);
+  console.log(`completed: ${plan.buckets.completed.join(', ') || '∅'}`);
+  if (plan.buckets.failed.length > 0) console.log(`failed: ${plan.buckets.failed.join(', ')}`);
+}
+
+function cmdPlan(session) {
+  if (!session) throw new Error('session name is required');
+  const file = refreshPlan(session);
+  console.log(relPosix(file));
+  console.log(JSON.stringify(readJson(file), null, 2));
+}
+
+function cmdValidate(session) {
+  if (!session) throw new Error('session name is required');
+  const errors = validateSession(session);
+  if (errors.length === 0) {
+    console.log(`✔ session '${slugify(session, 'session')}' artifacts conform to schemas/orchestration/*.schema.json`);
+    return;
+  }
+  console.error(`✖ ${errors.length} file(s) failed validation:`);
+  for (const e of errors) {
+    console.error(`  ${e.file}`);
+    for (const p of e.problems) console.error(`    - ${p}`);
+  }
+  process.exit(1);
 }
 
 function cmdList() {
@@ -161,9 +219,18 @@ function main() {
       case 'append':
         cmdAppend(positional[0], positional[1], positional[2], flags);
         break;
+      case 'complete':
+        cmdComplete(positional[0], positional[1], flags);
+        break;
       case 'status':
         cmdStatus(positional[0]);
         break;
+      case 'plan':
+        cmdPlan(positional[0]);
+        break;
+      case 'validate':
+        cmdValidate(positional[0]);
+        break;
       case 'list':
         cmdList();
         break;

package/skills/ai-ml/fine-tuning-expert/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: fine-tuning-expert
+description: "Use when fine-tuning LLMs, training custom models, or adapting foundation models for specific tasks. Invoke for configuring LoRA/QLoRA adapters, preparing JSONL training datasets, setting hyperparameters for fine-tuning runs, adapter training, transfer learning, finetuning with Hugging Face PEFT, OpenAI fine-tuning, instruction tuning, RLHF, DPO, or quantizing and deploying fine-tuned models. Trigger terms include: LoRA, QLoRA, PEFT, finetuning, fine-tuning, adapter tuning, LLM training, model training, custom model."
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: data-ml
+  triggers: fine-tuning, fine tuning, finetuning, LoRA, QLoRA, PEFT, adapter tuning, transfer learning, model training, custom model, LLM training, instruction tuning, RLHF, model optimization, quantization
+  role: expert
+  scope: implementation
+  output-format: code
+  related-skills: devops-engineer
+---
+
+# Fine-Tuning Expert
+
+Senior ML engineer specializing in LLM fine-tuning, parameter-efficient methods, and production model optimization.
+
+## Core Workflow
+
+1. **Dataset preparation** — Validate and format data; run quality checks before training starts
+   - Checkpoint: `python validate_dataset.py --input data.jsonl` — fix all errors before proceeding
+2. **Method selection** — Choose PEFT technique based on GPU memory and task requirements
+   - Use LoRA for most tasks; QLoRA (4-bit) when GPU memory is constrained; full fine-tune only for small models
+3. **Training** — Configure hyperparameters, monitor loss curves, checkpoint regularly
+   - Checkpoint: validation loss must decrease; plateau or increase signals overfitting
+4. **Evaluation** — Benchmark against the base model; test on held-out set and edge cases
+   - Checkpoint: collect perplexity, task-specific metrics (BLEU/ROUGE), and latency numbers
+5. **Deployment** — Merge adapter weights, quantize, measure inference throughput before serving
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| LoRA/PEFT | `references/lora-peft.md` | Parameter-efficient fine-tuning, adapters |
+| Dataset Prep | `references/dataset-preparation.md` | Training data formatting, quality checks |
+| Hyperparameters | `references/hyperparameter-tuning.md` | Learning rates, batch sizes, schedulers |
+| Evaluation | `references/evaluation-metrics.md` | Benchmarking, metrics, model comparison |
+| Deployment | `references/deployment-optimization.md` | Model merging, quantization, serving |
+
+## Minimal Working Example — LoRA Fine-Tuning with Hugging Face PEFT
+
+```python
+from datasets import load_dataset
+from transformers import AutoTokenizer, AutoModelForCausalLM, TrainingArguments
+from peft import LoraConfig, get_peft_model, TaskType
+from trl import SFTTrainer
+import torch
+
+# 1. Load base model and tokenizer
+model_id = "meta-llama/Llama-3-8B"
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+tokenizer.pad_token = tokenizer.eos_token
+
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    torch_dtype=torch.bfloat16,
+    device_map="auto",
+)
+
+# 2. Configure LoRA adapter
+lora_config = LoraConfig(
+    task_type=TaskType.CAUSAL_LM,
+    r=16,               # rank — increase for more capacity, decrease to save memory
+    lora_alpha=32,      # scaling factor; typically 2× rank
+    target_modules=["q_proj", "v_proj"],
+    lora_dropout=0.05,
+    bias="none",
+)
+model = get_peft_model(model, lora_config)
+model.print_trainable_parameters()  # verify: should be ~0.1–1% of total params
+
+# 3. Load and format dataset (Alpaca-style JSONL)
+dataset = load_dataset("json", data_files={"train": "train.jsonl", "test": "test.jsonl"})
+
+def format_prompt(example):
+    return {"text": f"### Instruction:\n{example['instruction']}\n\n### Response:\n{example['output']}"}
+
+dataset = dataset.map(format_prompt)
+
+# 4. Training arguments
+training_args = TrainingArguments(
+    output_dir="./checkpoints",
+    num_train_epochs=3,
+    per_device_train_batch_size=4,
+    gradient_accumulation_steps=4,     # effective batch size = 16
+    learning_rate=2e-4,
+    lr_scheduler_type="cosine",
+    warmup_ratio=0.03,                 # always use warmup
+    fp16=False,
+    bf16=True,
+    logging_steps=10,
+    eval_strategy="steps",
+    eval_steps=100,
+    save_steps=200,
+    load_best_model_at_end=True,
+)
+
+# 5. Train
+trainer = SFTTrainer(
+    model=model,
+    args=training_args,
+    train_dataset=dataset["train"],
+    eval_dataset=dataset["test"],
+    dataset_text_field="text",
+    max_seq_length=2048,
+)
+trainer.train()
+
+# 6. Save adapter weights only
+model.save_pretrained("./lora-adapter")
+tokenizer.save_pretrained("./lora-adapter")
+```
+
+**QLoRA variant** — add these lines before loading the model to enable 4-bit quantization:
+```python
+from transformers import BitsAndBytesConfig
+
+bnb_config = BitsAndBytesConfig(
+    load_in_4bit=True,
+    bnb_4bit_quant_type="nf4",
+    bnb_4bit_compute_dtype=torch.bfloat16,
+    bnb_4bit_use_double_quant=True,
+)
+model = AutoModelForCausalLM.from_pretrained(model_id, quantization_config=bnb_config, device_map="auto")
+```
+
+**Merge adapter into base model for deployment:**
+```python
+from peft import PeftModel
+
+base = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.bfloat16)
+merged = PeftModel.from_pretrained(base, "./lora-adapter").merge_and_unload()
+merged.save_pretrained("./merged-model")
+```
+
+## Constraints
+
+### MUST DO
+- Validate dataset quality before training
+- Use parameter-efficient methods for large models (>7B)
+- Monitor training/validation loss curves
+- Document hyperparameters and training config
+- Version datasets and model checkpoints
+- Always include a learning rate warmup
+
+### MUST NOT DO
+- Skip data quality validation
+- Overfit on small datasets — use regularisation (dropout, weight decay) and early stopping
+- Merge incompatible adapters (mismatched rank, base model, or target modules)
+- Deploy without evaluation against a held-out set and latency benchmark
+
+## Output Templates
+
+When implementing fine-tuning, always provide:
+1. **Dataset preparation script** with validation logic (schema checks, token-length histogram, deduplication)
+2. **Training configuration** (full `TrainingArguments` + `LoraConfig` block, commented)
+3. **Evaluation script** reporting perplexity, task-specific metrics, and latency
+4. **Brief design rationale** — why this PEFT method, rank, and learning rate were chosen for this task