specsmith 0.4.0.dev223__tar.gz → 0.5.0.dev225__tar.gz

{specsmith-0.4.0.dev223/src/specsmith.egg-info → specsmith-0.5.0.dev225}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.4.0.dev223
+Version: 0.5.0.dev225
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.4.0.dev223"
+version = "0.5.0.dev225"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225}/src/specsmith/agent/cleanup.py

@@ -68,6 +68,7 @@ PROTECTED_PATHS = frozenset(
         ".repo-index",
         ".github",
         ".vscode",
+        ".agents",
         ".warp",
         ".editorconfig",
         ".gitignore",

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225}/src/specsmith/cli.py

@@ -5532,6 +5532,415 @@ def cloud_spawn(utterance: str, project_dir: str, endpoint: str, dry_run: bool)
 main.add_command(cloud_group)
 
 
+# ---------------------------------------------------------------------------
+# Workflow — parameterised command snippets (Warp-style Workflows)
+# ---------------------------------------------------------------------------
+
+
+@main.group(name="workflow")
+def workflow_group() -> None:
+    """Record, list, and run parameterised command snippets.
+
+    Workflows are saved as YAML files under `.specsmith/workflows/<name>.yml`.
+    Each workflow has a name, an optional description, a command template
+    that may contain ``{{ param }}`` placeholders, and a list of accepted
+    params. ``specsmith workflow run <name>`` substitutes the params and
+    executes the resulting command via ``subprocess.run``.
+    """
+
+
+def _workflows_dir(root: Path) -> Path:
+    d = root / ".specsmith" / "workflows"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+@workflow_group.command(name="record")
+@click.argument("name")
+@click.option(
+    "--command",
+    "command",
+    required=True,
+    help="Command template. Use {{ param }} for substitution placeholders.",
+)
+@click.option("--description", "description", default="", help="Free-text description.")
+@click.option(
+    "--param",
+    "params",
+    multiple=True,
+    help="Declared parameter name (repeatable). Substituted at run time.",
+)
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def workflow_record(
+    name: str,
+    command: str,
+    description: str,
+    params: tuple[str, ...],
+    project_dir: str,
+) -> None:
+    """Save a workflow under .specsmith/workflows/<NAME>.yml."""
+    root = Path(project_dir).resolve()
+    target = _workflows_dir(root) / f"{name}.yml"
+    payload = {
+        "name": name,
+        "description": description,
+        "command": command,
+        "params": list(params),
+    }
+    target.write_text(yaml.safe_dump(payload, sort_keys=False), encoding="utf-8")
+    console.print(f"[green]\u2713[/green] Workflow recorded at {target.relative_to(root)}")
+
+
+@workflow_group.command(name="list")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--json", "as_json", is_flag=True, default=False, help="Emit JSON.")
+def workflow_list(project_dir: str, as_json: bool) -> None:
+    """List workflows recorded for this project."""
+    import json as _json
+
+    root = Path(project_dir).resolve()
+    wf_dir = _workflows_dir(root)
+    items: list[dict[str, Any]] = []
+    for path in sorted(wf_dir.glob("*.yml")):
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            continue
+        items.append(
+            {
+                "name": data.get("name", path.stem),
+                "description": data.get("description", ""),
+                "command": data.get("command", ""),
+                "params": list(data.get("params", [])),
+            }
+        )
+    if as_json:
+        click.echo(_json.dumps(items, indent=2))
+        return
+    if not items:
+        console.print("[dim]No workflows recorded.[/dim]")
+        return
+    for item in items:
+        params = ", ".join(item["params"]) or "(none)"
+        console.print(f"[bold]{item['name']}[/bold] — params: {params}")
+        if item["description"]:
+            console.print(f"  {item['description']}")
+        console.print(f"  [dim]{item['command']}[/dim]")
+
+
+@workflow_group.command(name="run")
+@click.argument("name")
+@click.option(
+    "--param",
+    "param_assignments",
+    multiple=True,
+    help="Parameter assignment in key=value form (repeatable).",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Print the resolved command without executing.",
+)
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def workflow_run(
+    name: str,
+    param_assignments: tuple[str, ...],
+    dry_run: bool,
+    project_dir: str,
+) -> None:
+    """Substitute parameters and execute the recorded workflow."""
+    import re
+    import shlex
+    import subprocess
+
+    root = Path(project_dir).resolve()
+    target = _workflows_dir(root) / f"{name}.yml"
+    if not target.is_file():
+        console.print(f"[red]No workflow named '{name}' at {target}[/red]")
+        raise SystemExit(1)
+    data = yaml.safe_load(target.read_text(encoding="utf-8")) or {}
+    template: str = data.get("command", "")
+    declared = list(data.get("params", []))
+
+    assignments: dict[str, str] = {}
+    for raw in param_assignments:
+        if "=" not in raw:
+            console.print(f"[red]Bad --param value: {raw!r} (expected key=value)[/red]")
+            raise SystemExit(2)
+        key, _, value = raw.partition("=")
+        assignments[key.strip()] = value
+
+    missing = [p for p in declared if p not in assignments]
+    if missing:
+        console.print(f"[red]Missing required params: {', '.join(missing)}[/red]")
+        raise SystemExit(2)
+
+    def _replace(match: re.Match[str]) -> str:
+        key = match.group(1).strip()
+        return assignments.get(key, match.group(0))
+
+    resolved = re.sub(r"\{\{\s*([^}]+?)\s*\}\}", _replace, template)
+
+    if dry_run:
+        console.print(f"[cyan]{resolved}[/cyan]")
+        return
+
+    args = shlex.split(resolved, posix=False) if resolved else []
+    if not args:
+        console.print("[red]Resolved workflow command is empty.[/red]")
+        raise SystemExit(2)
+    raise SystemExit(subprocess.call(args, cwd=str(root)))  # noqa: S603
+
+
+main.add_command(workflow_group)
+
+
+# ---------------------------------------------------------------------------
+# History — search across .specsmith/sessions/<id>/turns.jsonl (REQ-120)
+# ---------------------------------------------------------------------------
+
+
+@main.group(name="history")
+def history_group() -> None:
+    """Search and list persistent session memory written by `specsmith chat`."""
+
+
+def _sessions_dir(root: Path) -> Path:
+    return root / ".specsmith" / "sessions"
+
+
+@history_group.command(name="list")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--limit", type=int, default=20, help="Max number of sessions to list.")
+@click.option("--json", "as_json", is_flag=True, default=False)
+def history_list(project_dir: str, limit: int, as_json: bool) -> None:
+    """List the N most recent sessions with turn counts."""
+    import json as _json
+
+    root = Path(project_dir).resolve()
+    base = _sessions_dir(root)
+    if not base.is_dir():
+        if as_json:
+            click.echo("[]")
+        else:
+            console.print("[dim]No sessions recorded.[/dim]")
+        return
+    sessions = sorted(
+        (p for p in base.iterdir() if p.is_dir()),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )[:limit]
+    items: list[dict[str, Any]] = []
+    for sd in sessions:
+        turns_path = sd / "turns.jsonl"
+        count = 0
+        if turns_path.is_file():
+            with turns_path.open("r", encoding="utf-8") as fh:
+                count = sum(1 for line in fh if line.strip())
+        items.append({"session_id": sd.name, "turns": count, "path": str(turns_path)})
+    if as_json:
+        click.echo(_json.dumps(items, indent=2))
+        return
+    if not items:
+        console.print("[dim]No sessions recorded.[/dim]")
+        return
+    for item in items:
+        console.print(f"[bold]{item['session_id']}[/bold]  {item['turns']} turn(s)")
+
+
+@history_group.command(name="search")
+@click.argument("query")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--session", "session", default="", help="Limit to a specific session id.")
+@click.option("--limit", type=int, default=50, help="Max matching turns to print.")
+@click.option("--json", "as_json", is_flag=True, default=False)
+def history_search(
+    query: str,
+    project_dir: str,
+    session: str,
+    limit: int,
+    as_json: bool,
+) -> None:
+    """Print turns whose JSON content contains QUERY (case-insensitive substring)."""
+    import json as _json
+
+    root = Path(project_dir).resolve()
+    base = _sessions_dir(root)
+    if not base.is_dir():
+        if as_json:
+            click.echo("[]")
+        return
+    needle = query.lower()
+    targets = [base / session / "turns.jsonl"] if session else sorted(base.rglob("turns.jsonl"))
+    matches: list[dict[str, Any]] = []
+    for path in targets:
+        if not path.is_file():
+            continue
+        with path.open("r", encoding="utf-8") as fh:
+            for raw in fh:
+                if needle not in raw.lower():
+                    continue
+                try:
+                    turn = _json.loads(raw)
+                except _json.JSONDecodeError:
+                    continue
+                matches.append({"session_id": path.parent.name, "turn": turn})
+                if len(matches) >= limit:
+                    break
+        if len(matches) >= limit:
+            break
+    if as_json:
+        click.echo(_json.dumps(matches, indent=2))
+        return
+    if not matches:
+        console.print("[dim]No matches.[/dim]")
+        return
+    for hit in matches:
+        console.print(f"[bold]{hit['session_id']}[/bold]: {_json.dumps(hit['turn'])[:200]}")
+
+
+main.add_command(history_group)
+
+
+# ---------------------------------------------------------------------------
+# Drive — user-scoped sync for rules / workflows / notebooks / mcp configs
+# ---------------------------------------------------------------------------
+
+_DRIVE_KINDS = {
+    "rules": ("docs/governance",),
+    "workflows": (".specsmith/workflows",),
+    "notebooks": ("docs/notebooks",),
+    "mcp": (".specsmith/mcp.yml",),
+}
+
+
+def _drive_root() -> Path:
+    home = Path.home()
+    base = home / ".specsmith" / "drive"
+    base.mkdir(parents=True, exist_ok=True)
+    return base
+
+
+@main.group(name="drive")
+def drive_group() -> None:
+    """User-scoped Drive at ~/.specsmith/drive/ for rules / workflows / notebooks.
+
+    The Drive is a local, gitignored mirror of the four kinds of project
+    artefacts that users typically want to share across machines:
+    ``rules`` (docs/governance/*_RULES.md), ``workflows``
+    (.specsmith/workflows/*.yml), ``notebooks`` (docs/notebooks/*.md), and
+    ``mcp`` (.specsmith/mcp.yml). Cloud sync is left to the user's preferred
+    backup tool — Drive is a stable canonical location, not a server.
+    """
+
+
+@drive_group.command(name="list")
+@click.option("--json", "as_json", is_flag=True, default=False)
+def drive_list(as_json: bool) -> None:
+    """Show the contents of ~/.specsmith/drive/ grouped by kind."""
+    import json as _json
+
+    base = _drive_root()
+    items: dict[str, list[str]] = {}
+    for kind in _DRIVE_KINDS:
+        kind_dir = base / kind
+        if not kind_dir.is_dir():
+            items[kind] = []
+            continue
+        items[kind] = sorted(
+            str(p.relative_to(kind_dir)) for p in kind_dir.rglob("*") if p.is_file()
+        )
+    if as_json:
+        click.echo(_json.dumps(items, indent=2))
+        return
+    for kind, paths in items.items():
+        console.print(f"[bold]{kind}[/bold] ({len(paths)} item(s))")
+        for rel in paths:
+            console.print(f"  {rel}")
+
+
+@drive_group.command(name="push")
+@click.argument("kind", type=click.Choice(sorted(_DRIVE_KINDS.keys())))
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def drive_push(kind: str, project_dir: str) -> None:
+    """Copy this project's KIND artefacts into ~/.specsmith/drive/KIND/."""
+    import shutil
+
+    root = Path(project_dir).resolve()
+    base = _drive_root() / kind
+    base.mkdir(parents=True, exist_ok=True)
+    sources = _DRIVE_KINDS[kind]
+    copied = 0
+    for rel in sources:
+        src = root / rel
+        if not src.exists():
+            continue
+        if src.is_file():
+            shutil.copy2(src, base / src.name)
+            copied += 1
+            continue
+        for path in src.rglob("*"):
+            if not path.is_file():
+                continue
+            target = base / path.relative_to(src)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(path, target)
+            copied += 1
+    console.print(f"[green]\u2713[/green] Pushed {copied} file(s) to {base}")
+
+
+@drive_group.command(name="pull")
+@click.argument("kind", type=click.Choice(sorted(_DRIVE_KINDS.keys())))
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--force", is_flag=True, default=False, help="Overwrite existing project files.")
+def drive_pull(kind: str, project_dir: str, force: bool) -> None:
+    """Copy KIND artefacts from ~/.specsmith/drive/ into this project.
+
+    Existing project files are preserved unless --force is supplied.
+    """
+    import shutil
+
+    root = Path(project_dir).resolve()
+    base = _drive_root() / kind
+    if not base.is_dir():
+        console.print(f"[yellow]Drive has no {kind!r} entries yet.[/yellow]")
+        return
+    target_root = root / _DRIVE_KINDS[kind][0]
+    pulled = skipped = 0
+    if base.is_dir() and target_root.suffix == "":
+        target_root.mkdir(parents=True, exist_ok=True)
+        for path in base.rglob("*"):
+            if not path.is_file():
+                continue
+            dest = target_root / path.relative_to(base)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            if dest.exists() and not force:
+                skipped += 1
+                continue
+            shutil.copy2(path, dest)
+            pulled += 1
+    else:
+        # Single-file kind (e.g. mcp.yml).
+        for path in base.iterdir():
+            if not path.is_file():
+                continue
+            dest = root / _DRIVE_KINDS[kind][0]
+            if dest.exists() and not force:
+                skipped += 1
+                continue
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(path, dest)
+            pulled += 1
+    console.print(
+        f"[green]\u2713[/green] Pulled {pulled} file(s) into {target_root}; "
+        f"skipped {skipped} (use --force to overwrite)."
+    )
+
+
+main.add_command(drive_group)
+
+
 # ---------------------------------------------------------------------------
 # AG2 Agent Shell
 # ---------------------------------------------------------------------------

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225}/src/specsmith/config.py

@@ -198,7 +198,10 @@ class ProjectConfig(BaseModel):
     # Agent integrations
     integrations: list[str] = Field(
         default=["agents-md"],
-        description="Agent integrations to generate (agents-md, warp, claude-code, cursor, etc.)",
+        description=(
+            "Agent integrations to generate (agents-md, agent-skill, claude-code, "
+            "cursor, copilot, gemini, windsurf, aider)."
+        ),
     )
 
     # Agent execution profile

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225}/src/specsmith/credits.py

@@ -17,7 +17,7 @@ class CreditEntry:
     timestamp: str = ""
     session_id: str = ""
     model: str = ""
-    provider: str = ""  # openai, anthropic, google, warp, local
+    provider: str = ""  # openai, anthropic, google, local, ollama, etc.
     tokens_in: int = 0
     tokens_out: int = 0
     estimated_cost_usd: float = 0.0

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225}/src/specsmith/integrations/__init__.py

@@ -11,19 +11,30 @@ if TYPE_CHECKING:
 
 ADAPTER_REGISTRY: dict[str, type[AgentAdapter]] = {}
 
+# Legacy adapter names that have been superseded. Mapped to the current
+# canonical name. Lookups for legacy keys still succeed (backward compat for
+# existing scaffold.yml files) but only the canonical names are returned by
+# ``list_adapters()``.
+LEGACY_ALIASES: dict[str, str] = {
+    # Pre-0.5.0 the agent-skill adapter shipped under the name ``warp`` and
+    # wrote to ``.warp/skills/SKILL.md``. New scaffolds use ``agent-skill``
+    # and ``.agents/skills/SKILL.md``.
+    "warp": "agent-skill",
+}
+
 
 def _load_adapters() -> None:
     """Populate the adapter registry."""
+    from specsmith.integrations.agent_skill import AgentSkillAdapter
     from specsmith.integrations.aider import AiderAdapter
     from specsmith.integrations.claude_code import ClaudeCodeAdapter
     from specsmith.integrations.copilot import CopilotAdapter
     from specsmith.integrations.cursor import CursorAdapter
     from specsmith.integrations.gemini import GeminiAdapter
-    from specsmith.integrations.warp import WarpAdapter
     from specsmith.integrations.windsurf import WindsurfAdapter
 
     for cls in (
-        WarpAdapter,
+        AgentSkillAdapter,
         ClaudeCodeAdapter,
         CursorAdapter,
         CopilotAdapter,
@@ -35,10 +46,16 @@ def _load_adapters() -> None:
 
 
 def get_adapter(name: str) -> AgentAdapter:
-    """Get an adapter instance by name."""
+    """Get an adapter instance by name.
+
+    Legacy names listed in :data:`LEGACY_ALIASES` are silently rewritten to
+    their canonical equivalent, so older ``scaffold.yml`` integration lists
+    keep working without manual migration.
+    """
     if not ADAPTER_REGISTRY:
         _load_adapters()
-    cls = ADAPTER_REGISTRY.get(name)
+    resolved = LEGACY_ALIASES.get(name, name)
+    cls = ADAPTER_REGISTRY.get(resolved)
     if cls is None:
         available = ", ".join(sorted(ADAPTER_REGISTRY.keys()))
         msg = f"Unknown integration '{name}'. Available: {available}"
@@ -47,7 +64,7 @@ def get_adapter(name: str) -> AgentAdapter:
 
 
 def list_adapters() -> list[str]:
-    """List available adapter names."""
+    """List available adapter names (canonical only; legacy aliases hidden)."""
     if not ADAPTER_REGISTRY:
         _load_adapters()
     return sorted(ADAPTER_REGISTRY.keys())

specsmith-0.4.0.dev223/src/specsmith/integrations/warp.py → specsmith-0.5.0.dev225/src/specsmith/integrations/agent_skill.py

@@ -1,6 +1,16 @@
 # SPDX-License-Identifier: MIT
 # Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
-"""Warp / Oz skill integration adapter."""
+"""Agent skill integration adapter.
+
+Generates a generic ``SKILL.md`` file under ``.agents/skills/`` for any
+terminal-native AI agent that supports the SKILL.md convention.
+
+This adapter previously shipped under the name ``warp`` and wrote to
+``.warp/skills/SKILL.md``. The legacy name is still resolved as an alias
+in :mod:`specsmith.integrations` so existing ``scaffold.yml`` configs
+continue to work, but the canonical adapter name is ``agent-skill`` and
+the canonical output path is ``.agents/skills/SKILL.md``.
+"""
 
 from __future__ import annotations
 
@@ -10,19 +20,19 @@ from specsmith.config import ProjectConfig
 from specsmith.integrations.base import AgentAdapter
 
 
-class WarpAdapter(AgentAdapter):
-    """Generate a Warp skill file for the project."""
+class AgentSkillAdapter(AgentAdapter):
+    """Generate a generic agent skill file (.agents/skills/SKILL.md)."""
 
     @property
     def name(self) -> str:
-        return "warp"
+        return "agent-skill"
 
     @property
     def description(self) -> str:
-        return "Warp / Oz skill file (.warp/skills/)"
+        return "Agent skill file (.agents/skills/SKILL.md)"
 
     def generate(self, config: ProjectConfig, target: Path) -> list[Path]:
-        skill_dir = target / ".warp" / "skills"
+        skill_dir = target / ".agents" / "skills"
         skill_dir.mkdir(parents=True, exist_ok=True)
 
         skill_path = skill_dir / "SKILL.md"
@@ -87,7 +97,7 @@ Before marking any task complete, run: {verify_line}
 ## Credit Tracking
 After completing tasks, record token usage:
 ```
-specsmith credits record --model <model> --provider <provider> \
+specsmith credits record --model <model> --provider <provider> \\
   --tokens-in <N> --tokens-out <N> --task "<desc>"
 ```
 Check budget: `specsmith credits summary`

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225}/src/specsmith/integrations/base.py

@@ -16,7 +16,7 @@ class AgentAdapter(ABC):
     @property
     @abstractmethod
     def name(self) -> str:
-        """Short identifier for this integration (e.g. 'warp', 'claude-code')."""
+        """Short identifier for this integration (e.g. 'agent-skill', 'claude-code')."""
 
     @property
     @abstractmethod

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225}/src/specsmith/upgrader.py

@@ -368,6 +368,10 @@ def _update_references(
         "AGENTS.md",
         "CLAUDE.md",
         "GEMINI.md",
+        # Canonical post-0.5.0 path for the agent-skill adapter.
+        ".agents/skills/SKILL.md",
+        # Legacy path for projects scaffolded before 0.5.0 (still patched
+        # so reference rewrites continue to work after rename).
         ".warp/skills/SKILL.md",
         ".cursor/rules/governance.mdc",
         ".windsurfrules",

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225/src/specsmith.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.4.0.dev223
+Version: 0.5.0.dev225
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT

{specsmith-0.4.0.dev223 → specsmith-0.5.0.dev225}/src/specsmith.egg-info/SOURCES.txt

@@ -91,13 +91,13 @@ src/specsmith/gui/widgets/token_meter.py
 src/specsmith/gui/widgets/tool_panel.py
 src/specsmith/gui/widgets/update_checker.py
 src/specsmith/integrations/__init__.py
+src/specsmith/integrations/agent_skill.py
 src/specsmith/integrations/aider.py
 src/specsmith/integrations/base.py
 src/specsmith/integrations/claude_code.py
 src/specsmith/integrations/copilot.py
 src/specsmith/integrations/cursor.py
 src/specsmith/integrations/gemini.py
-src/specsmith/integrations/warp.py
 src/specsmith/integrations/windsurf.py
 src/specsmith/templates/agents.md.j2
 src/specsmith/templates/editorconfig.j2
@@ -152,6 +152,7 @@ src/specsmith/vcs/gitlab.py
 tests/test_CMD_001.py
 tests/test_auditor.py
 tests/test_cli.py
+tests/test_cli_workflows_history_drive.py
 tests/test_compressor.py
 tests/test_e2e_nexus.py
 tests/test_epistemic.py