Feat/langchain adopter

README.md

@@ -158,6 +158,80 @@ Define `bootstrap.md` and `teardown.md` in the `hooks/` folder to control what a
 
 <img src="patterns/agent-automation-hooks.png" alt="Agent Lifecycle Hooks" width="600" />
 
+### SkillsFlow
+Deterministic, multi-step workflows defined in `workflows/` as YAML. Chain `skill:`, `agent:`, and `tool:` steps with `depends_on` ordering, `${{ }}` template data flow, and per-step `prompt:` overrides. Every run follows the same path — no LLM discretion on execution order.
+
+```yaml
+name: code-review-flow
+description: Full code review pipeline
+triggers:
+  - pull_request
+
+steps:
+  lint:
+    skill: static-analysis
+    inputs:
+      path: ${{ trigger.changed_files }}
+
+  review:
+    agent: code-reviewer
+    depends_on: [lint]
+    prompt: |
+      Focus on security and performance.
+      Flag any use of eval() or raw SQL.
+    inputs:
+      findings: ${{ steps.lint.outputs.issues }}
+
+  test:
+    tool: bash
+    depends_on: [lint]
+    inputs:
+      command: "npm test -- --coverage"
+
+  report:
+    skill: review-summary
+    depends_on: [review, test]
+    conditions:
+      - ${{ steps.review.outputs.severity != 'none' }}
+    inputs:
+      review: ${{ steps.review.outputs.comments }}
+      coverage: ${{ steps.test.outputs.report }}
+
+error_handling:
+  on_failure: notify
+  channel: "#eng-reviews"
+```
+
+### Porting Framework Agents to GitAgent
+
+Agents built in frameworks like NVIDIA AIQ, LangGraph, or CrewAI have their identity split across config files, Jinja2 templates, and Python code. gitagent extracts the **identity layer** — prompts, rules, roles, tool schemas — into a portable, versionable format.
+
+> **What ports cleanly:** system prompts, persona definitions, hard constraints, tool schemas, role/SOD policies, model preferences.
+>
+> **What stays in the framework:** runtime orchestration (state machines, graph wiring), live tool execution, memory I/O, iterative loops.
+
+This pattern is demonstrated with [NVIDIA's AIQ Deep Researcher](https://github.com/NVIDIA-AI-Blueprints/aiq) — a 3-agent hierarchy (orchestrator → planner → researcher) that produces cited research reports. The gitagent version captures the agent's identity, rules, and SOD policy so you can:
+
+- **Fork for a new domain** — edit `SOUL.md` for legal/medical/finance research without touching Python
+- **Version prompts independently** — `git diff` when the orchestrator's style regresses
+- **Validate SOD** — `gitagent validate --compliance` ensures the orchestrator can't also be the researcher
+- **Export to other runtimes** — same identity on Claude Code, OpenAI, or as a raw system prompt
+
+```
+examples/nvidia-deep-researcher/
+├── agent.yaml                  # Manifest + SOD policy
+├── SOUL.md                     # Orchestrator identity (from orchestrator.j2)
+├── RULES.md                    # Citation rules, report constraints
+├── DUTIES.md                   # Role separation: orchestrator ↔ planner ↔ researcher
+├── agents/planner/             # Planner sub-agent (from planner.j2)
+├── agents/researcher/          # Researcher sub-agent (from researcher.j2)
+├── skills/{web,paper,knowledge}-search/
+├── tools/*.yaml                # MCP-compatible tool schemas
+└── config/                     # Model assignments per environment
+```
+
+See [`examples/nvidia-deep-researcher/`](examples/nvidia-deep-researcher/) for the full working example.
+
 ## Quick Start
 
 ```bash
@@ -232,7 +306,7 @@ compliance:
 | `gitagent validate [--compliance]` | Validate against spec and regulatory requirements |
 | `gitagent info` | Display agent summary |
 | `gitagent export --format <fmt>` | Export to other formats (see adapters below) |
-| `gitagent import --from <fmt> <path>` | Import (`claude`, `cursor`, `crewai`) |
+| `gitagent import --from <fmt> <path>` | Import (`claude`, `cursor`, `crewai`, `opencode`) |
 | `gitagent run <source> --adapter <a>` | Run an agent from a git repo or local directory |
 | `gitagent install` | Resolve and install git-based dependencies |
 | `gitagent audit` | Generate compliance audit report |
@@ -282,6 +356,7 @@ Adapters are used by both `export` and `run`. Available adapters:
 | `lyzr` | Lyzr Studio agent |
 | `github` | GitHub Actions agent |
 | `git` | Git-native execution (run only) |
+| `opencode` | OpenCode instructions + config |
 | `openclaw` | OpenClaw format |
 | `nanobot` | Nanobot format |
 | `langchain` | LangChain agent Python code |

docs/comparison.md

@@ -0,0 +1,157 @@
+# gitagent vs. Alternatives: A Comparison
+
+> How does gitagent differ from other approaches to defining, versioning, and running AI agents?
+
+This document compares gitagent against three common alternatives developers reach for when they need to deploy a reusable AI agent: the **Agent Definition Language (ADL)** (and similar emerging formats), **raw YAML/JSON config files**, and **no-standard / framework-native definitions** (inline code).
+
+---
+
+## TL;DR
+
+| Dimension | gitagent | ADL / Emerging Formats | Raw YAML/JSON | Framework-Native (inline code) |
+|-----------|----------|----------------------|---------------|-------------------------------|
+| **Where does the agent live?** | Git repository = the agent | Separate spec file, usually checked into a repo | Config file(s) checked into a repo | Python/TypeScript class, checked into a repo |
+| **Portable across frameworks?** | ✅ Yes — `export` to 9+ targets | ⚠️ Depends on adoption | ❌ No — framework-specific parsers | ❌ No — tied to one framework |
+| **Runnable from repo URL?** | ✅ `gitagent run -r github.com/org/agent` | ❌ No | ❌ No | ❌ No |
+| **Version-controlled identity** | ✅ Git tags = agent versions | ⚠️ Optional | ⚠️ Manual | ⚠️ Git blame only |
+| **Compliance / audit built-in** | ✅ Yes — FINRA, SEC, CFPB, SR 11-7 fields | ❌ No | ❌ No | ❌ No |
+| **Multi-agent topology** | ✅ Native `agents:` block + SOD | ❌ No standard | ❌ No | ⚠️ Framework-specific |
+| **Skills / reusable capabilities** | ✅ `skills/` directory, installable via `npx skills add` | ❌ No | ❌ No | ❌ No |
+| **Human-in-the-loop model** | ✅ Branch + PR = agent learning | ❌ No | ❌ No | ❌ No |
+
+---
+
+## 1. gitagent vs. ADL (Agent Definition Language)
+
+ADL and similar emerging formats (e.g., proposals in the A2A / MCP ecosystem) define a structured schema for describing agent capabilities, inputs, and outputs — typically as a single JSON or YAML file.
+
+### How they differ
+
+**gitagent** treats the entire *repository* as the agent. It is not a single file — it is a directory standard where `agent.yaml` anchors identity but `SOUL.md`, `RULES.md`, `skills/`, `knowledge/`, `hooks/`, and `memory/` collectively form the agent’s complete definition. The repository is the unit of deployment.
+
+**ADL** (and similar specs) describe an agent’s *interface* — what it can do, what inputs it accepts, what outputs it produces. It is closer to an OpenAPI spec for agents than a deployable agent.
+
+### When to use which
+
+- **gitagent**: You want a deployable, runnable agent that can be cloned, versioned with git tags, exported to multiple frameworks, and audited for compliance. The agent has rich behavioral context (skills, knowledge, memory, compliance rules) not just a capability schema.
+- **ADL/Interface Specs**: You are building an agent registry or marketplace where agents advertise capabilities for discovery — not for direct execution. ADL describes what the agent *is*; gitagent describes how the agent *behaves and runs*.
+
+### Can they coexist?
+
+Yes. A gitagent repository can include an ADL-formatted capability manifest in `agent.yaml` under the `tools` or `capabilities` block. They are not mutually exclusive.
+
+---
+
+## 2. gitagent vs. Raw YAML/JSON
+
+Many teams define agents with hand-rolled YAML files that are parsed by custom code — a `config.yaml` with system prompt, model, temperature, tool list, etc.
+
+### How they differ
+
+**Raw YAML/JSON** gives you full flexibility but zero standardization. Every team invents their own schema, every framework reads it differently, and there is no tooling layer.
+
+**gitagent** gives you a *community standard* schema with:
+- A validated `agent.yaml` spec (run `gitagent validate` to check conformance)
+- A CLI layer (`gitagent export`, `gitagent run`, `gitagent audit`) that acts on the standard
+- Installable skills from a shared ecosystem (`npx skills add`)
+- A compliance block that maps to real regulatory frameworks (FINRA 3110/4511, SEC 17a-4, SR 11-7, CFPB) — not invented fields
+
+### When to use which
+
+- **gitagent**: Team of 2+ people, agents that need to be portable, regulated industries (finance, healthcare, legal), agents that will evolve over time.
+- **Raw YAML/JSON**: Solo prototype, one-off experiment, framework-specific config that will never leave one codebase.
+
+### The migration path
+
+Raw YAML → gitagent is straightforward:
+```bash
+gitagent init -t minimal  # scaffold the standard layout
+# copy your system prompt → SOUL.md
+# copy your rules → RULES.md
+# move your config fields into agent.yaml
+gitagent validate         # check conformance
+```
+
+---
+
+## 3. gitagent vs. Framework-Native (Inline Code)
+
+LangChain agents, CrewAI agents, AutoGen agents, etc. are all defined as Python or TypeScript classes — the agent’s identity, prompt, tools, and memory are wired together in code.
+
+### How they differ
+
+**Framework-native code** is the most powerful approach — full programming language expressivity, tight integration with the framework’s ecosystem. But it is:
+- **Not portable** — a CrewAI agent cannot be trivially run with OpenAI Agents SDK
+- **Not auditable** as a unit — you need to read through code to understand what the agent will do
+- **Not versioned semantically** — git history gives you line-level diffs, not “agent v2.1.0 changed the compliance policy”
+
+**gitagent** sits *above* frameworks. You define the agent once in the standard format, then export to the framework of your choice:
+
+```bash
+gitagent export -f crewai    # → YAML config for CrewAI
+gitagent export -f openai    # → Python script for OpenAI Agents SDK
+gitagent export -f langchain # → Python script for LangChain
+gitagent export -f langgraph # → Python StateGraph for LangGraph
+gitagent export -f claude-code  # → CLAUDE.md for Claude Code
+```
+
+The framework-native implementation becomes a *derived artifact* of the canonical gitagent definition, not the source of truth.
+
+### When to use which
+
+- **gitagent**: Multi-framework deployment, compliance requirements, team collaboration, long-lived agents that need version history.
+- **Framework-native**: Deep framework integration, performance-critical code paths, prototype that will stay within one framework indefinitely.
+
+### The hybrid pattern
+
+Many teams combine both: gitagent defines the agent’s identity, compliance, and skills; framework-native code handles tool implementations, memory backends, and custom orchestration. The `gitagent export` output is a starting point, not a locked output.
+
+---
+
+## 4. The Compliance Dimension
+
+This is where gitagent has no direct equivalent.
+
+gitagent’s `agent.yaml` compliance block maps directly to financial regulatory requirements:
+
+```yaml
+compliance:
+  framework: FINRA
+  rules:
+    - rule: "3110"        # Supervision
+      description: All agent outputs must be reviewed before client delivery
+    - rule: "4511"        # Books and records
+      description: All interactions logged to immutable audit trail
+  communications:
+    fair_balanced: true   # FINRA 2210
+    no_misleading: true
+  data_governance:
+    pii_handling: redact
+    retention_years: 7    # SEC 17a-4
+  supervision:
+    human_in_the_loop: always
+  segregation_of_duties:
+    conflicts:
+      - [maker, checker]  # No agent may both make and check its own work
+```
+
+Running `gitagent audit` against this produces a structured compliance report. No other agent definition format offers this.
+
+For teams building agents in regulated industries — financial services, healthcare (HIPAA), or any environment governed by SEC/FINRA/CFPB/MiCA rules — gitagent’s compliance model is the primary differentiator.
+
+---
+
+## Summary
+
+gitagent is not a competitor to LangChain, CrewAI, or framework-native code — it is a layer *above* them that provides:
+
+1. **A portable identity** — the repository *is* the agent, exportable to any framework
+2. **Semantic versioning** — git tags map to agent versions; changes are auditable
+3. **A compliance model** — maps to real regulatory frameworks, not invented abstractions
+4. **A shared skills ecosystem** — reusable capabilities installable across agents
+
+If you are building a one-off prototype, raw code or YAML is fine. If you are building agents that will run in production, evolve over time, or need to satisfy audit requirements — gitagent provides the structural discipline to do it right.
+
+---
+
+*Contributions welcome. Open an issue or PR if you see gaps, inaccuracies, or additional frameworks worth comparing.*

examples/full/skills/document-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: document-review
-description: Review financial documents for completeness and compliance
+description: "Reviews financial documents (prospectuses, ADVs, marketing materials) for FINRA 2210 compliance, required disclosures, and balanced presentation. Use when reviewing financial statements, audit documents, regulatory filings, or when the user mentions compliance checks, financial audits, or document verification."
 license: proprietary
 allowed-tools: search-regulations generate-report
 metadata:
@@ -29,3 +29,23 @@ When reviewing a financial document:
 - [ ] Proper disclaimers included
 - [ ] Correct classification (correspondence/retail/institutional)
 - [ ] Principal pre-approval status verified (if retail communication)
+
+## Output Format
+
+For each finding, produce:
+
+```
+### [SEVERITY] — [Rule Reference]
+- **Issue**: [What was found]
+- **Location**: [Section/page reference]
+- **Recommended action**: [Specific fix]
+```
+
+### Example Finding
+
+```
+### WARNING — FINRA 2210(d)(1)(A)
+- **Issue**: Performance claim "consistently outperforms the market" lacks supporting data and time period
+- **Location**: Page 2, paragraph 3
+- **Recommended action**: Add specific time period, benchmark comparison, and standardized performance data per SEC Rule 482
+```

examples/full/skills/regulatory-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: regulatory-analysis
-description: Analyze documents and processes for regulatory compliance
+description: "Analyzes documents and processes against FINRA, SEC, Federal Reserve, and CFPB regulatory frameworks. Identifies compliance gaps, classifies findings by severity, and recommends remediation. Use when performing compliance audits, regulatory reviews, gap analyses, or verifying policy adherence to financial regulations."
 license: proprietary
 allowed-tools: search-regulations
 metadata:
@@ -22,6 +22,7 @@ When analyzing a document or process for regulatory compliance:
 4. **Classify findings** — Rate each finding by severity (CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL)
 5. **Recommend remediation** — Provide specific, actionable steps to address each finding
 6. **Assess confidence** — Rate your confidence in each finding (HIGH, MEDIUM, LOW)
+7. **Validate citations** — Verify all cited rules exist and are current before finalizing
 
 ## Regulatory Priority Order
 When multiple frameworks apply, prioritize in this order:
@@ -66,3 +67,14 @@ When multiple frameworks apply, prioritize in this order:
 ### Disclaimer
 This analysis is for informational purposes only and does not constitute legal advice.
 ```
+
+### Example Finding
+
+```
+#### CRITICAL
+- **Inadequate Suitability Disclosure** — FINRA Rule 2111
+  - Issue: Customer account agreement lacks suitability questionnaire for complex products
+  - Evidence: Section 4.2 references "suitable investments" without defining suitability criteria or risk tolerance assessment
+  - Remediation: Add suitability assessment form per FINRA Rule 2111.05 (Supplementary Material) before account opening
+  - Confidence: HIGH
+```

examples/gitagent-helper/skills/create-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-agent
-description: Guide users through agent.yaml configuration, SOUL.md writing, and directory structure
+description: "Creates and configures agent.yaml files, writes SOUL.md personality definitions, and sets up agent directory structures with skills, tools, and knowledge. Use when the user wants to configure an agent, create agent.yaml, write SOUL.md, set up agent directory structure, or customize agent settings."
 license: MIT
 metadata:
   author: gitagent
@@ -10,8 +10,13 @@ metadata:
 
 # Create & Configure Agents
 
-## When to Use
-When a user wants to customize their agent.yaml, write a good SOUL.md, add skills/tools/knowledge, or set up compliance.
+## Quick Start
+
+1. Create directory structure: `mkdir -p my-agent/skills`
+2. Write `agent.yaml` with required fields (see below)
+3. Create `SOUL.md` with agent identity
+4. Add skills, tools, and knowledge as needed
+5. Validate: `gitagent validate -d ./my-agent`
 
 ## agent.yaml Reference
 

examples/gitagent-helper/skills/export-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: export-agent
-description: Help users export agents to other frameworks and import from existing tools
+description: "Converts agent definitions between frameworks — exports to Claude Code, OpenAI, CrewAI, Lyzr, and GitHub Models formats, and imports from Claude, Cursor, and CrewAI projects. Use when the user wants to convert an agent, migrate to another framework, export to LangChain/AutoGen/CrewAI, or import from existing automation tools."
 license: MIT
 metadata:
   author: gitagent
@@ -10,8 +10,14 @@ metadata:
 
 # Export & Import Agents
 
-## When to Use
-When a user wants to convert their agent to another framework format, or import an existing agent into gitagent.
+## Verify Export
+
+After exporting, check the output matches expectations:
+
+```bash
+# Verify export file was created and contains agent name
+gitagent export -f system-prompt -d ./my-agent | head -5
+```
 
 ## Export
 

examples/gitagent-helper/skills/get-started/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: get-started
-description: Help users install gitagent and create their first agent from scratch
+description: "Guides installation of gitagent and creation of first agent with scaffolding, configuration, and validation. Use when the user is new to gitagent, asks how to get started, wants to install gitagent, set up their first agent, or says 'how do I start?'"
 license: MIT
 metadata:
   author: gitagent

examples/gitagent-helper/skills/manage-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-skills
-description: Help users search, install, create, and manage agent skills
+description: "Searches the SkillsMP registry, installs skills locally or globally, creates custom skills with SKILL.md frontmatter, and manages the skill lifecycle. Use when the user wants to find skills, add new capabilities, install a skill, browse available skills, create a custom skill, or manage the skills system."
 license: MIT
 metadata:
   author: gitagent
@@ -13,6 +13,14 @@ metadata:
 ## When to Use
 When a user wants to find skills, install them, create new ones, or understand the skills system.
 
+## Verify Installation
+
+After installing a skill, confirm it's available:
+
+```bash
+gitagent skills list -d ./my-agent | grep "code-review"
+```
+
 ## Search Skills
 
 ```bash