@full-self-developing/fsd 1.0.0

package/skills/iterative-retrieval/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: iterative-retrieval
+description: Pattern for progressively refining context retrieval to solve the subagent context problem
+origin: ECC
+---
+
+# Iterative Retrieval Pattern
+
+Solves the "context problem" in multi-agent workflows where subagents don't know what context they need until they start working.
+
+## When to Activate
+
+- Spawning subagents that need codebase context they cannot predict upfront
+- Building multi-agent workflows where context is progressively refined
+- Encountering "context too large" or "missing context" failures in agent tasks
+- Designing RAG-like retrieval pipelines for code exploration
+- Optimizing token usage in agent orchestration
+
+## The Problem
+
+Subagents are spawned with limited context. They don't know:
+- Which files contain relevant code
+- What patterns exist in the codebase
+- What terminology the project uses
+
+Standard approaches fail:
+- **Send everything**: Exceeds context limits
+- **Send nothing**: Agent lacks critical information
+- **Guess what's needed**: Often wrong
+
+## The Solution: Iterative Retrieval
+
+A 4-phase loop that progressively refines context:
+
+```
+┌─────────────────────────────────────────────┐
+│                                             │
+│   ┌──────────┐      ┌──────────┐            │
+│   │ DISPATCH │─────│ EVALUATE │            │
+│   └──────────┘      └──────────┘            │
+│        ▲                  │                 │
+│        │                  ▼                 │
+│   ┌──────────┐      ┌──────────┐            │
+│   │   LOOP   │─────│  REFINE  │            │
+│   └──────────┘      └──────────┘            │
+│                                             │
+│        Max 3 cycles, then proceed           │
+└─────────────────────────────────────────────┘
+```
+
+### Phase 1: DISPATCH
+
+Initial broad query to gather candidate files:
+
+```javascript
+// Start with high-level intent
+const initialQuery = {
+  patterns: ['src/**/*.ts', 'lib/**/*.ts'],
+  keywords: ['authentication', 'user', 'session'],
+  excludes: ['*.test.ts', '*.spec.ts']
+};
+
+// Dispatch to retrieval agent
+const candidates = await retrieveFiles(initialQuery);
+```
+
+### Phase 2: EVALUATE
+
+Assess retrieved content for relevance:
+
+```javascript
+function evaluateRelevance(files, task) {
+  return files.map(file => ({
+    path: file.path,
+    relevance: scoreRelevance(file.content, task),
+    reason: explainRelevance(file.content, task),
+    missingContext: identifyGaps(file.content, task)
+  }));
+}
+```
+
+Scoring criteria:
+- **High (0.8-1.0)**: Directly implements target functionality
+- **Medium (0.5-0.7)**: Contains related patterns or types
+- **Low (0.2-0.4)**: Tangentially related
+- **None (0-0.2)**: Not relevant, exclude
+
+### Phase 3: REFINE
+
+Update search criteria based on evaluation:
+
+```javascript
+function refineQuery(evaluation, previousQuery) {
+  return {
+    // Add new patterns discovered in high-relevance files
+    patterns: [...previousQuery.patterns, ...extractPatterns(evaluation)],
+
+    // Add terminology found in codebase
+    keywords: [...previousQuery.keywords, ...extractKeywords(evaluation)],
+
+    // Exclude confirmed irrelevant paths
+    excludes: [...previousQuery.excludes, ...evaluation
+      .filter(e => e.relevance < 0.2)
+      .map(e => e.path)
+    ],
+
+    // Target specific gaps
+    focusAreas: evaluation
+      .flatMap(e => e.missingContext)
+      .filter(unique)
+  };
+}
+```
+
+### Phase 4: LOOP
+
+Repeat with refined criteria (max 3 cycles):
+
+```javascript
+async function iterativeRetrieve(task, maxCycles = 3) {
+  let query = createInitialQuery(task);
+  let bestContext = [];
+
+  for (let cycle = 0; cycle < maxCycles; cycle++) {
+    const candidates = await retrieveFiles(query);
+    const evaluation = evaluateRelevance(candidates, task);
+
+    // Check if we have sufficient context
+    const highRelevance = evaluation.filter(e => e.relevance >= 0.7);
+    if (highRelevance.length >= 3 && !hasCriticalGaps(evaluation)) {
+      return highRelevance;
+    }
+
+    // Refine and continue
+    query = refineQuery(evaluation, query);
+    bestContext = mergeContext(bestContext, highRelevance);
+  }
+
+  return bestContext;
+}
+```
+
+## Practical Examples
+
+### Example 1: Bug Fix Context
+
+```
+Task: "Fix the authentication token expiry bug"
+
+Cycle 1:
+  DISPATCH: Search for "token", "auth", "expiry" in src/**
+  EVALUATE: Found auth.ts (0.9), tokens.ts (0.8), user.ts (0.3)
+  REFINE: Add "refresh", "jwt" keywords; exclude user.ts
+
+Cycle 2:
+  DISPATCH: Search refined terms
+  EVALUATE: Found session-manager.ts (0.95), jwt-utils.ts (0.85)
+  REFINE: Sufficient context (2 high-relevance files)
+
+Result: auth.ts, tokens.ts, session-manager.ts, jwt-utils.ts
+```
+
+### Example 2: Feature Implementation
+
+```
+Task: "Add rate limiting to API endpoints"
+
+Cycle 1:
+  DISPATCH: Search "rate", "limit", "api" in routes/**
+  EVALUATE: No matches - codebase uses "throttle" terminology
+  REFINE: Add "throttle", "middleware" keywords
+
+Cycle 2:
+  DISPATCH: Search refined terms
+  EVALUATE: Found throttle.ts (0.9), middleware/index.ts (0.7)
+  REFINE: Need router patterns
+
+Cycle 3:
+  DISPATCH: Search "router", "express" patterns
+  EVALUATE: Found router-setup.ts (0.8)
+  REFINE: Sufficient context
+
+Result: throttle.ts, middleware/index.ts, router-setup.ts
+```
+
+## Integration with Agents
+
+Use in agent prompts:
+
+```markdown
+When retrieving context for this task:
+1. Start with broad keyword search
+2. Evaluate each file's relevance (0-1 scale)
+3. Identify what context is still missing
+4. Refine search criteria and repeat (max 3 cycles)
+5. Return files with relevance >= 0.7
+```
+
+## Best Practices
+
+1. **Start broad, narrow progressively** - Don't over-specify initial queries
+2. **Learn codebase terminology** - First cycle often reveals naming conventions
+3. **Track what's missing** - Explicit gap identification drives refinement
+4. **Stop at "good enough"** - 3 high-relevance files beats 10 mediocre ones
+5. **Exclude confidently** - Low-relevance files won't become relevant
+
+## Related
+
+- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) - Subagent orchestration section
+- `continuous-learning` skill - For patterns that improve over time
+- Agent definitions bundled with ECC (manual install path: `agents/`)

package/skills/php-security/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: php-security
+description: PHP and ThinkPHP 5.0 security best practices, including common vulnerabilities (RCE, SQLi, XSS) and hardening.
+origin: ECC (Adapted for ThinkPHP 5.0)
+---
+
+# PHP/ThinkPHP Security Best Practices
+
+Comprehensive security guidance for ThinkPHP 5.0 applications to protect against common vulnerabilities.
+
+## Common ThinkPHP 5.0 Vulnerabilities
+
+### 1. Remote Code Execution (RCE)
+ThinkPHP 5.x has historically been vulnerable to RCE through controller/method manipulation in the URL.
+- **Fix**: Ensure you are on ThinkPHP **5.0.24** or higher.
+- **Check**: Look at `thinkphp/base.php` or `thinkphp/VERSION` for version information.
+
+### 2. SQL Injection
+Even with Query Builder, improper use of `whereRaw` or direct `Db::query` can lead to SQLi.
+- **Best Practice**: Always use parameter binding or standard Query Builder methods (`where(['id' => $id])`).
+- **Avoid**: `Db::query("SELECT * FROM users WHERE id = $id")` (Direct interpolation).
+
+### 3. Debug Mode Leakage
+Leaving `app_debug` set to `true` in production exposes stack traces and environment variables.
+- **Setting**: `application/config.php` -> `'app_debug' => false`.
+
+## Core Security Hardening
+
+### Input Validation
+Always use the `Validate` class for all user-provided data.
+- **Example**:
+```php
+$rule = [
+    'id'  => 'require|number',
+    'name' => 'require|max:25',
+];
+$data = ['id' => 1, 'name' => 'thinkphp'];
+$validate = new \think\Validate($rule);
+if (!$validate->check($data)) {
+    dump($validate->getError());
+}
+```
+
+### XSS Prevention
+Sanitize all user-generated content before rendering.
+- Use `htmlspecialchars()` or ThinkPHP's `input('param', '', 'filter')` helper.
+- **Blade/Templates**: Ensure output is escaped.
+
+### CSRF Protection
+ThinkPHP 5.0 includes a token mechanism for form submission.
+- **Usage**: Use `token()` in forms and verify in the controller.
+
+## Secrets and Credentials
+- Never hardcode database credentials in `application/database.php`. Use environment variables or a `.env` file if supported.
+- Ensure `runtime/` and `file/` directories are not publicly accessible via the web server.
+
+## File Upload Safety
+- Validate MIME type, extension, and file size.
+- Store uploads outside the web root if possible.
+- Avoid using predictable filenames.
+```php
+$file = request()->file('image');
+$info = $file->validate(['size'=>15678,'ext'=>'jpg,png,gif'])->move(ROOT_PATH . 'public' . DS . 'uploads');
+```
+
+## Success Metrics
+- No hardcoded secrets in the codebase.
+- `app_debug` is disabled in production.
+- All database queries use parameter binding.
+- All user inputs are validated.

package/skills/php-security/rules/thinkphp-security.rules

@@ -0,0 +1,23 @@
+# ThinkPHP 5.0 Security Rules (Grep Patterns)
+
+## SQL Injection (Raw Queries)
+# Identify whereRaw or Db::query with potential interpolation
+grep -r "whereRaw" application/
+grep -r "Db::query" application/
+grep -r "->query(" application/
+
+## RCE (Method/Controller manipulation)
+# Check for vulnerable ThinkPHP versions (below 5.0.24)
+grep "'VERSION'" thinkphp/base.php
+
+## Insecure Configuration
+# Check if app_debug is true in production
+grep "'app_debug'" application/config.php | grep "true"
+
+## Insecure File Uploads
+# Check for missing extension validation in move()
+grep -r "->move(" application/ | grep -v "validate"
+
+## Hardcoded Credentials
+# Scan database.php for potential hardcoded production passwords
+grep -C 5 "'password'" application/database.php

package/skills/requirement-ears/SKILL.md

@@ -0,0 +1,31 @@
+# EARS (Easy Approach to Requirements Syntax)
+
+This skill provides templates and patterns for writing clear, unambiguous requirements for TheOMS.
+
+## Requirement Types
+
+| Type | Template | When to Use |
+|------|----------|-------------|
+| **Ubiquitous** | The `<system>` shall `<action>`. | For always-active behavior. |
+| **Event-driven** | When `<trigger>`, the `<system>` shall `<action>`. | For actions triggered by events (e.g., API calls, webhooks). |
+| **State-driven** | While `<state>`, the `<system>` shall `<action>`. | For behavior active during a specific state (e.g., while order is 'pending'). |
+| **Conditional** | If `<condition>`, then the `<system>` shall `<action>`. | For logic branching based on data or environment. |
+| **Unwanted Behavior** | If `<condition>`, then the `<system>` shall `<response>`. | For error handling and validation (e.g., invalid input). |
+
+## TheOMS Examples
+
+### API & Controller
+- **Event-driven**: When a `POST` request is sent to `/api/v1/order/refund`, the system shall validate the `order_id` and `amount`.
+- **Unwanted Behavior**: If the refund amount exceeds the original order amount, then the system shall return a `400 Bad Request` with error code `REFUND_EXCEEDS_TOTAL`.
+
+### Business Logic (Service Layer)
+- **Conditional**: If the user has a "VIP" membership, then the system shall apply a 10% discount to all purchase items.
+- **State-driven**: While an inventory item is marked as "restricted", the system shall prevent it from being added to new purchase orders.
+
+### Security
+- **Ubiquitous**: The system shall sanitize all user-provided HTML input using `htmlspecialchars` before database storage.
+
+## Best Practices
+1. **Be Specific**: Use exact field names or model names.
+2. **Avoid Ambiguity**: Avoid words like "fast", "efficient", or "user-friendly". Use measurable criteria.
+3. **Traceability**: Each requirement must have a unique ID (e.g., `REQ-1`).

package/skills/rules-distill/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: rules-distill
+description: "Scan skills to extract cross-cutting principles and distill them into rules — append, revise, or create new rule files"
+origin: ECC
+---
+
+# Rules Distill
+
+Scan installed skills, extract cross-cutting principles that appear in multiple skills, and distill them into rules — appending to existing rule files, revising outdated content, or creating new rule files.
+
+Applies the "deterministic collection + LLM judgment" principle: scripts collect facts exhaustively, then an LLM cross-reads the full context and produces verdicts.
+
+## When to Use
+
+- Periodic rules maintenance (monthly or after installing new skills)
+- After a skill-stocktake reveals patterns that should be rules
+- When rules feel incomplete relative to the skills being used
+
+## How It Works
+
+The rules distillation process follows three phases:
+
+### Phase 1: Inventory (Deterministic Collection)
+
+#### 1a. Collect skill inventory
+
+```bash
+bash ~/.claude/skills/rules-distill/scripts/scan-skills.sh
+```
+
+#### 1b. Collect rules index
+
+```bash
+bash ~/.claude/skills/rules-distill/scripts/scan-rules.sh
+```
+
+#### 1c. Present to user
+
+```
+Rules Distillation — Phase 1: Inventory
+────────────────────────────────────────
+Skills: {N} files scanned
+Rules:  {M} files ({K} headings indexed)
+
+Proceeding to cross-read analysis...
+```
+
+### Phase 2: Cross-read, Match & Verdict (LLM Judgment)
+
+Extraction and matching are unified in a single pass. Rules files are small enough (~800 lines total) that the full text can be provided to the LLM — no grep pre-filtering needed.
+
+#### Batching
+
+Group skills into **thematic clusters** based on their descriptions. Analyze each cluster in a subagent with the full rules text.
+
+#### Cross-batch Merge
+
+After all batches complete, merge candidates across batches:
+- Deduplicate candidates with the same or overlapping principles
+- Re-check the "2+ skills" requirement using evidence from **all** batches combined — a principle found in 1 skill per batch but 2+ skills total is valid
+
+#### Subagent Prompt
+
+Launch a general-purpose Agent with the following prompt:
+
+````
+You are an analyst who cross-reads skills to extract principles that should be promoted to rules.
+
+## Input
+- Skills: {full text of skills in this batch}
+- Existing rules: {full text of all rule files}
+
+## Extraction Criteria
+
+Include a candidate ONLY if ALL of these are true:
+
+1. **Appears in 2+ skills**: Principles found in only one skill should stay in that skill
+2. **Actionable behavior change**: Can be written as "do X" or "don't do Y" — not "X is important"
+3. **Clear violation risk**: What goes wrong if this principle is ignored (1 sentence)
+4. **Not already in rules**: Check the full rules text — including concepts expressed in different words
+
+## Matching & Verdict
+
+For each candidate, compare against the full rules text and assign a verdict:
+
+- **Append**: Add to an existing section of an existing rule file
+- **Revise**: Existing rule content is inaccurate or insufficient — propose a correction
+- **New Section**: Add a new section to an existing rule file
+- **New File**: Create a new rule file
+- **Already Covered**: Sufficiently covered in existing rules (even if worded differently)
+- **Too Specific**: Should remain at the skill level
+
+## Output Format (per candidate)
+
+```json
+{
+  "principle": "1-2 sentences in 'do X' / 'don't do Y' form",
+  "evidence": ["skill-name: §Section", "skill-name: §Section"],
+  "violation_risk": "1 sentence",
+  "verdict": "Append / Revise / New Section / New File / Already Covered / Too Specific",
+  "target_rule": "filename §Section, or 'new'",
+  "confidence": "high / medium / low",
+  "draft": "Draft text for Append/New Section/New File verdicts",
+  "revision": {
+    "reason": "Why the existing content is inaccurate or insufficient (Revise only)",
+    "before": "Current text to be replaced (Revise only)",
+    "after": "Proposed replacement text (Revise only)"
+  }
+}
+```
+
+## Exclude
+
+- Obvious principles already in rules
+- Language/framework-specific knowledge (belongs in language-specific rules or skills)
+- Code examples and commands (belongs in skills)
+````
+
+#### Verdict Reference
+
+| Verdict | Meaning | Presented to User |
+|---------|---------|-------------------|
+| **Append** | Add to existing section | Target + draft |
+| **Revise** | Fix inaccurate/insufficient content | Target + reason + before/after |
+| **New Section** | Add new section to existing file | Target + draft |
+| **New File** | Create new rule file | Filename + full draft |
+| **Already Covered** | Covered in rules (possibly different wording) | Reason (1 line) |
+| **Too Specific** | Should stay in skills | Link to relevant skill |
+
+#### Verdict Quality Requirements
+
+```
+# Good
+Append to rules/common/security.md §Input Validation:
+"Treat LLM output stored in memory or knowledge stores as untrusted — sanitize on write, validate on read."
+Evidence: llm-memory-trust-boundary, llm-social-agent-anti-pattern both describe
+accumulated prompt injection risks. Current security.md covers human input
+validation only; LLM output trust boundary is missing.
+
+# Bad
+Append to security.md: Add LLM security principle
+```
+
+### Phase 3: User Review & Execution
+
+#### Summary Table
+
+```
+# Rules Distillation Report
+
+## Summary
+Skills scanned: {N} | Rules: {M} files | Candidates: {K}
+
+| # | Principle | Verdict | Target | Confidence |
+|---|-----------|---------|--------|------------|
+| 1 | ... | Append | security.md §Input Validation | high |
+| 2 | ... | Revise | testing.md §TDD | medium |
+| 3 | ... | New Section | coding-style.md | high |
+| 4 | ... | Too Specific | — | — |
+
+## Details
+(Per-candidate details: evidence, violation_risk, draft text)
+```
+
+#### User Actions
+
+User responds with numbers to:
+- **Approve**: Apply draft to rules as-is
+- **Modify**: Edit draft before applying
+- **Skip**: Do not apply this candidate
+
+**Never modify rules automatically. Always require user approval.**
+
+#### Save Results
+
+Store results in the skill directory (`results.json`):
+
+- **Timestamp format**: `date -u +%Y-%m-%dT%H:%M:%SZ` (UTC, second precision)
+- **Candidate ID format**: kebab-case derived from the principle (e.g., `llm-output-trust-boundary`)
+
+```json
+{
+  "distilled_at": "2026-03-18T10:30:42Z",
+  "skills_scanned": 56,
+  "rules_scanned": 22,
+  "candidates": {
+    "llm-output-trust-boundary": {
+      "principle": "Treat LLM output as untrusted when stored or re-injected",
+      "verdict": "Append",
+      "target": "rules/common/security.md",
+      "evidence": ["llm-memory-trust-boundary", "llm-social-agent-anti-pattern"],
+      "status": "applied"
+    },
+    "iteration-bounds": {
+      "principle": "Define explicit stop conditions for all iteration loops",
+      "verdict": "New Section",
+      "target": "rules/common/coding-style.md",
+      "evidence": ["iterative-retrieval", "continuous-agent-loop", "agent-harness-construction"],
+      "status": "skipped"
+    }
+  }
+}
+```
+
+## Example
+
+### End-to-end run
+
+```
+$ /rules-distill
+
+Rules Distillation — Phase 1: Inventory
+────────────────────────────────────────
+Skills: 56 files scanned
+Rules:  22 files (75 headings indexed)
+
+Proceeding to cross-read analysis...
+
+[Subagent analysis: Batch 1 (agent/meta skills) ...]
+[Subagent analysis: Batch 2 (coding/pattern skills) ...]
+[Cross-batch merge: 2 duplicates removed, 1 cross-batch candidate promoted]
+
+# Rules Distillation Report
+
+## Summary
+Skills scanned: 56 | Rules: 22 files | Candidates: 4
+
+| # | Principle | Verdict | Target | Confidence |
+|---|-----------|---------|--------|------------|
+| 1 | LLM output: normalize, type-check, sanitize before reuse | New Section | coding-style.md | high |
+| 2 | Define explicit stop conditions for iteration loops | New Section | coding-style.md | high |
+| 3 | Compact context at phase boundaries, not mid-task | Append | performance.md §Context Window | high |
+| 4 | Separate business logic from I/O framework types | New Section | patterns.md | high |
+
+## Details
+
+### 1. LLM Output Validation
+Verdict: New Section in coding-style.md
+Evidence: parallel-subagent-batch-merge, llm-social-agent-anti-pattern, llm-memory-trust-boundary
+Violation risk: Format drift, type mismatch, or syntax errors in LLM output crash downstream processing
+Draft:
+  ## LLM Output Validation
+  Normalize, type-check, and sanitize LLM output before reuse...
+  See skill: parallel-subagent-batch-merge, llm-memory-trust-boundary
+
+[... details for candidates 2-4 ...]
+
+Approve, modify, or skip each candidate by number:
+> User: Approve 1, 3. Skip 2, 4.
+
+✓ Applied: coding-style.md §LLM Output Validation
+✓ Applied: performance.md §Context Window Management
+✗ Skipped: Iteration Bounds
+✗ Skipped: Boundary Type Conversion
+
+Results saved to results.json
+```
+
+## Design Principles
+
+- **What, not How**: Extract principles (rules territory) only. Code examples and commands stay in skills.
+- **Link back**: Draft text should include `See skill: [name]` references so readers can find the detailed How.
+- **Deterministic collection, LLM judgment**: Scripts guarantee exhaustiveness; the LLM guarantees contextual understanding.
+- **Anti-abstraction safeguard**: The 3-layer filter (2+ skills evidence, actionable behavior test, violation risk) prevents overly abstract principles from entering rules.

package/skills/rules-distill/scripts/scan-rules.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# scan-rules.sh — enumerate rule files and extract H2 heading index
+# Usage: scan-rules.sh [RULES_DIR]
+# Output: JSON to stdout
+#
+# Environment:
+#   RULES_DISTILL_DIR  Override ~/.claude/rules (for testing only)
+
+set -euo pipefail
+
+RULES_DIR="${RULES_DISTILL_DIR:-${1:-$HOME/.claude/rules}}"
+
+if [[ ! -d "$RULES_DIR" ]]; then
+  jq -n --arg path "$RULES_DIR" '{"error":"rules directory not found","path":$path}' >&2
+  exit 1
+fi
+
+# Collect all .md files (excluding _archived/)
+files=()
+while IFS= read -r f; do
+  files+=("$f")
+done < <(find "$RULES_DIR" -name '*.md' -not -path '*/_archived/*' -print | sort)
+
+total=${#files[@]}
+
+tmpdir=$(mktemp -d)
+_rules_cleanup() { rm -rf "$tmpdir"; }
+trap _rules_cleanup EXIT
+
+for i in "${!files[@]}"; do
+  file="${files[$i]}"
+  rel_path="${file#"$HOME"/}"
+  rel_path="~/$rel_path"
+
+  # Extract H2 headings (## Title) into a JSON array via jq
+  headings_json=$({ grep -E '^## ' "$file" 2>/dev/null || true; } | sed 's/^## //' | jq -R . | jq -s '.')
+
+  # Get line count
+  line_count=$(wc -l < "$file" | tr -d ' ')
+
+  jq -n \
+    --arg path "$rel_path" \
+    --arg file "$(basename "$file")" \
+    --argjson lines "$line_count" \
+    --argjson headings "$headings_json" \
+    '{path:$path,file:$file,lines:$lines,headings:$headings}' \
+    > "$tmpdir/$i.json"
+done
+
+if [[ ${#files[@]} -eq 0 ]]; then
+  jq -n --arg dir "$RULES_DIR" '{rules_dir:$dir,total:0,rules:[]}'
+else
+  jq -n \
+    --arg dir "$RULES_DIR" \
+    --argjson total "$total" \
+    --argjson rules "$(jq -s '.' "$tmpdir"/*.json)" \
+    '{rules_dir:$dir,total:$total,rules:$rules}'
+fi