karajan-cli 0.1.0__py3-none-any.whl

karajan/__init__.py

@@ -0,0 +1,4 @@
+"""Karajan package."""
+
+__version__ = "0.1.0"
+

karajan/agents/architect.md

@@ -0,0 +1,23 @@
+---
+name: architect
+description: Technical planning agent. Designs solutions, writes ADRs, and produces implementation specs. Use before any coding task.
+model: google/gemini-2.0-flash
+temperature: 0.3
+mode: primary
+tools:
+  - read
+  - write
+permissions:
+  allow:
+    - read: "**"
+    - write: ".agent/DECISIONS.md"
+    - write: ".workflow-state/**"
+  deny:
+    - write: "src/**"
+    - write: "*.ts"
+    - write: "*.py"
+    - bash: "*"
+---
+
+You are a Software Architect with deep experience in TypeScript, Node.js, event-driven systems, and complex integrations.
+

karajan/agents/qa.md

@@ -0,0 +1,13 @@
+---
+name: qa
+description: QA validation agent. Runs tests, verifies acceptance criteria, surfaces edge cases.
+model: ollama/qwen2.5:7b
+temperature: 0.1
+mode: primary
+tools:
+  - read
+  - bash
+---
+
+You are a QA Engineer.
+

karajan/agents/researcher.md

@@ -0,0 +1,13 @@
+---
+name: researcher
+description: Technical research agent. Gathers context, finds patterns, identifies risks before design begins. Always runs before architect.
+model: google/gemini-2.0-flash
+temperature: 0.2
+mode: primary
+tools:
+  - read
+  - web_search
+---
+
+You are a Technical Research Specialist.
+

karajan/agents/reviewer.md

@@ -0,0 +1,13 @@
+---
+name: reviewer
+description: Code review agent. Reviews diffs for correctness, conventions, and quality.
+model: google/gemini-2.0-flash
+temperature: 0.1
+mode: primary
+tools:
+  - read
+  - bash
+---
+
+You are a Tech Lead doing code review.
+

karajan/cli.py

@@ -0,0 +1,102 @@
+"""Karajan CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Sequence
+
+from . import __version__
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="karajan",
+        description="An AI agent harness for software engineers. Built on opencode + LangGraph.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser("init", help="Initialize in current project")
+    init_parser.add_argument("--profile", "-p", choices=["solo", "team"], default=None)
+    init_parser.add_argument("--force", "-f", action="store_true")
+
+    task_parser = subparsers.add_parser("task", help="Run full workflow")
+    task_parser.add_argument("ticket")
+    task_parser.add_argument("--model", "-m", default=None)
+    task_parser.add_argument("--dev-model", default=None)
+    task_parser.add_argument("--qa-model", default=None)
+    task_parser.add_argument("--from-stage", default=None)
+    task_parser.add_argument("--dry-run", action="store_true")
+
+    status_parser = subparsers.add_parser("status", help="Show active workflows")
+    status_parser.add_argument("ticket", nargs="?", default=None)
+
+    models_parser = subparsers.add_parser("models", help="List available models")
+    models_parser.add_argument("--provider", default=None)
+
+    config_parser = subparsers.add_parser("config", help="Show current project config")
+    config_parser.add_argument("--show", action="store_true")
+    config_parser.add_argument("--set", dest="set_key", default=None)
+
+    subparsers.add_parser("version", help="Show version")
+    subparsers.add_parser("profiles", help="List profiles and defaults")
+
+    logs_parser = subparsers.add_parser("logs", help="Show run logs and cost summary")
+    logs_parser.add_argument("ticket", nargs="?", default=None)
+    logs_parser.add_argument("--tail", "-n", type=int, default=20)
+    logs_parser.add_argument("--summary", "-s", action="store_true")
+
+    return parser
+
+
+def app(argv: Sequence[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        raise SystemExit(0)
+
+    if args.command == "init":
+        from .commands.init import run_init
+
+        run_init(profile=args.profile, force=args.force)
+    elif args.command == "task":
+        from .commands.task import run_task
+
+        run_task(
+            ticket=args.ticket,
+            model=args.model,
+            dev_model=args.dev_model,
+            qa_model=args.qa_model,
+            from_stage=args.from_stage,
+            dry_run=args.dry_run,
+        )
+    elif args.command == "status":
+        from .commands.status import run_status
+
+        run_status(ticket=args.ticket)
+    elif args.command == "models":
+        from .commands.models import run_models
+
+        run_models(provider=args.provider)
+    elif args.command == "config":
+        from .commands.config import run_config
+
+        run_config(show=args.show, set_key=args.set_key)
+    elif args.command == "version":
+        print(f"karajan v{__version__}")
+    elif args.command == "profiles":
+        from .commands.profiles import run_profiles
+
+        run_profiles()
+    elif args.command == "logs":
+        from .commands.logs import run_logs
+
+        run_logs(ticket=args.ticket, tail=args.tail, summary=args.summary)
+    else:
+        parser.error(f"Unknown command: {args.command}")
+
+
+if __name__ == "__main__":
+    app()
+

karajan/commands/__init__.py

@@ -0,0 +1,2 @@
+"""Karajan command implementations."""
+

karajan/commands/config.py

@@ -0,0 +1,89 @@
+"""Show or update Karajan config."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from ..config import dump_config_toml, load_config
+
+
+def run_config(show: bool = False, set_key: str = None):
+    config_path = Path(".karajan/config.toml")
+
+    if set_key:
+        _set_config_value(config_path, set_key)
+        return
+
+    if show or not config_path.exists():
+        config = load_config()
+        print(dump_config_toml(config.model_dump()))
+        return
+
+    print(config_path.read_text(encoding="utf-8"))
+
+
+def _set_config_value(config_path: Path, assignment: str):
+    if not config_path.exists():
+        print("No .karajan/config.toml found. Run karajan init first.")
+        raise SystemExit(1)
+    if "=" not in assignment:
+        print(f"Invalid config assignment: {assignment}")
+        raise SystemExit(1)
+    key, raw_value = (part.strip() for part in assignment.split("=", 1))
+    parts = [part for part in key.split(".") if part]
+    if not key or len(parts) != len(key.split(".")) or len(parts) > 2:
+        print(f"Invalid config path: {key}")
+        raise SystemExit(1)
+    with config_path.open("rb") as handle:
+        config = tomllib.load(handle)
+    target = _coerce_config_value(raw_value)
+    if len(parts) == 1:
+        if isinstance(config.get(parts[0]), dict):
+            print(f"Invalid config path: {key}")
+            raise SystemExit(1)
+        config[parts[0]] = target
+    else:
+        section, field = parts
+        section_data = config.get(section)
+        if section_data is None:
+            config[section] = {field: target}
+        elif isinstance(section_data, dict):
+            section_data[field] = target
+        else:
+            print(f"Invalid config path: {key}")
+            raise SystemExit(1)
+    _write_config(config_path, config)
+    print(f"✅ Set {key} = {_format_config_value(target)}")
+
+
+def _coerce_config_value(raw_value: str):
+    value = raw_value.strip()
+    lowered = value.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    try:
+        return int(value)
+    except ValueError:
+        try:
+            return float(value)
+        except ValueError:
+            return value
+
+
+def _format_config_value(value) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _write_config(config_path: Path, config: dict):
+    try:
+        import tomli_w
+    except ModuleNotFoundError:
+        config_path.write_text(dump_config_toml(config), encoding="utf-8")
+        return
+    with config_path.open("wb") as handle:
+        tomli_w.dump(config, handle)

karajan/commands/init.py

@@ -0,0 +1,247 @@
+"""Initialize Karajan in a project."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+CONTEXT_MD = """# {project_name} - Context
+
+## What is this
+One sentence. What problem does it solve and for whom.
+
+## Current state
+Phase: exploration / mvp / production / maintenance
+
+## Immediate goal
+What you want to achieve in the next work sessions.
+
+## Important context
+Anything an agent needs to know that isn't obvious from the code.
+"""
+
+STACK_MD = """# Stack - {project_name}
+
+## Runtime
+- Node X / Python X
+
+## Framework
+-
+
+## Database
+-
+
+## Infrastructure
+-
+
+## Key dependencies
+-
+
+## Pending decisions
+- [ ]
+"""
+
+DECISIONS_MD = """# Decisions - {project_name}
+
+## YYYY-MM - Decision title
+**Decided:** what was chosen
+**Why:** reasoning
+**Discarded:** what was rejected and why
+**Revisit when:** condition that would make you reconsider
+"""
+
+CONSTRAINTS_MD = """# Constraints - {project_name}
+
+## Never touch without discussing
+-
+
+## Never add without approval
+- New dependencies
+- Breaking API changes
+
+## Agent autonomy limits
+- Agent CAN: create files, add tests, refactor within a module
+- Agent NEEDS APPROVAL: schema changes, new dependencies, config changes
+- Agent NEVER: push to main directly
+"""
+
+TASKS_MD = """# Tasks - {project_name}
+
+## In progress
+- [ ]
+
+## Next
+- [ ]
+
+## Done this week
+- [x]
+"""
+
+AGENTS_MD = """# Agent Instructions - {project_name}
+
+## Before any task
+1. Read CONTEXT.md
+2. Read STACK.md
+3. Read CONSTRAINTS.md
+4. Read TASKS.md
+
+## How to work here
+- TypeScript strict - no `any`
+- Atomic commits per logical change
+- Tests required for non-trivial logic
+- If spec is ambiguous: choose conservative option + leave TODO comment
+
+## What agent CAN do without asking
+- Create files and components
+- Add tests
+- Refactor within same module
+- Update docs
+
+## What NEEDS approval
+- New dependencies
+- Schema/migration changes
+- Changes to public API
+- Anything touching production config
+"""
+
+KARAJAN_CONFIG = """# Karajan config - {project_name}
+# Docs: https://github.com/TU_USER/karajan
+
+profile = "{profile}"
+
+[models]
+# Override profile defaults here if needed
+
+[tracker]
+type = "{tracker_type}"
+
+[dev_cli]
+tool = "{dev_cli}"
+
+[observability]
+enabled = false
+provider = "local"
+"""
+
+
+def run_init(profile: str = None, force: bool = False):
+    project_name = Path.cwd().name
+    print(f"\nKarajan init - {project_name}\n")
+
+    if not profile:
+        profile = input("Profile [solo/team] (solo): ").strip() or "solo"
+    if profile not in {"solo", "team"}:
+        raise ValueError("Profile must be 'solo' or 'team'.")
+
+    tracker_type = "github" if profile == "solo" else "jira"
+    dev_cli = "opencode" if profile == "solo" else "claude"
+
+    karajan_dir = Path(".karajan")
+    if karajan_dir.exists() and not force:
+        overwrite = input(".karajan/ already exists. Overwrite? [y/N]: ").strip().lower()
+        if overwrite not in {"y", "yes"}:
+            print("Aborted.")
+            return
+
+    karajan_dir.mkdir(exist_ok=True)
+    agent_dir = Path(".agent")
+    agent_dir.mkdir(exist_ok=True)
+
+    files = {
+        agent_dir / "CONTEXT.md": CONTEXT_MD.format(project_name=project_name),
+        agent_dir / "STACK.md": STACK_MD.format(project_name=project_name),
+        agent_dir / "DECISIONS.md": DECISIONS_MD.format(project_name=project_name),
+        agent_dir / "CONSTRAINTS.md": CONSTRAINTS_MD.format(project_name=project_name),
+        agent_dir / "TASKS.md": TASKS_MD.format(project_name=project_name),
+        agent_dir / "AGENTS.md": AGENTS_MD.format(project_name=project_name),
+        karajan_dir / "config.toml": KARAJAN_CONFIG.format(
+            project_name=project_name,
+            profile=profile,
+            tracker_type=tracker_type,
+            dev_cli=dev_cli,
+        ),
+    }
+
+    for path, content in files.items():
+        if not path.exists() or force:
+            path.write_text(content, encoding="utf-8")
+            print(f"  + {path}")
+        else:
+            print(f"  skip {path} (exists)")
+
+    env_example = Path(".env.karajan.example")
+    if not env_example.exists() or force:
+        _write_env_example(env_example, profile)
+        print(f"  + {env_example}")
+
+    _copy_agent_definitions(profile, force=force)
+
+    if profile == "solo":
+        _setup_github()
+
+    print(f"\nKarajan initialized ({profile} profile)\n")
+
+
+def _write_env_example(path: Path, profile: str):
+    solo_vars = """
+KARAJAN_MODEL_REASONING=google/gemini-2.0-flash
+KARAJAN_MODEL_DEV=ollama/qwen2.5-coder:14b
+KARAJAN_MODEL_QA=ollama/qwen2.5:7b
+
+GEMINI_API_KEY=
+GITHUB_TOKEN=
+GITHUB_REPO=TU_USER/repo-name
+GITHUB_BASE_BRANCH=main
+"""
+    team_vars = """
+KARAJAN_MODEL_REASONING=google/gemini-2.0-flash
+KARAJAN_MODEL_DEV=anthropic/claude-sonnet-4-20250514
+KARAJAN_MODEL_QA=anthropic/claude-haiku-4-5
+
+GEMINI_API_KEY=
+ANTHROPIC_API_KEY=
+JIRA_BASE_URL=https://empresa.atlassian.net
+JIRA_EMAIL=tu@empresa.com
+JIRA_API_TOKEN=
+GITHUB_TOKEN=
+GITHUB_REPO=empresa/repo-name
+GITHUB_BASE_BRANCH=main
+LANGFUSE_HOST=https://cloud.langfuse.com
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_SECRET_KEY=
+"""
+    path.write_text(solo_vars if profile == "solo" else team_vars, encoding="utf-8")
+
+
+def _setup_github():
+    try:
+        result = subprocess.run(["gh", "--version"], capture_output=True, text=True)
+        if result.returncode != 0:
+            return
+    except FileNotFoundError:
+        return
+
+
+def _copy_agent_definitions(profile: str, force: bool = False):
+    agents_src = Path(__file__).resolve().parent.parent / "agents"
+    agents_dst = Path(".agents")
+    agents_dst.mkdir(parents=True, exist_ok=True)
+
+    for agent_file in agents_src.glob("*.md"):
+        dst = agents_dst / agent_file.name
+        if dst.exists() and not force:
+            print(f"  skip {dst} (exists)")
+            continue
+
+        content = agent_file.read_text(encoding="utf-8")
+        if profile == "team":
+            content = content.replace(
+                "model: google/gemini-2.0-flash",
+                "model: anthropic/claude-sonnet-4-20250514",
+            ).replace(
+                "model: ollama/qwen2.5:7b",
+                "model: anthropic/claude-haiku-4-5",
+            )
+        dst.write_text(content, encoding="utf-8")
+        print(f"  + {dst}")

karajan/commands/logs.py

@@ -0,0 +1,30 @@
+"""Show run logs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..scripts.logger import KarajanLogger
+
+
+def run_logs(ticket: str = None, tail: int = 20, summary: bool = False):
+    log_file = Path(".workflow-state/runs.log")
+    if not log_file.exists():
+        print("No runs logged yet")
+        return
+
+    if summary and ticket:
+        KarajanLogger().print_summary(ticket)
+        return
+
+    lines = log_file.read_text(encoding="utf-8").splitlines()
+    if ticket:
+        lines = [line for line in lines if ticket in line]
+
+    if not lines:
+        print("No runs logged yet")
+        return
+
+    for line in lines[-tail:]:
+        print(line)
+

karajan/commands/models.py

@@ -0,0 +1,49 @@
+"""List available models."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Optional
+
+
+RECOMMENDED = {
+    "solo": [
+        ("google/gemini-2.0-flash", "Research, Architect, PRD, Reviewer", "Free tier"),
+        ("ollama/qwen2.5-coder:14b", "Dev agent", "Local, free"),
+        ("ollama/qwen2.5:7b", "QA agent", "Local, free, fast"),
+    ],
+    "team": [
+        ("google/gemini-2.0-flash", "Research, Architect, PRD, Reviewer", "Free tier"),
+        ("anthropic/claude-sonnet-4-20250514", "Dev agent (Claude Code)", "Paid"),
+        ("anthropic/claude-haiku-4-5", "QA agent", "Paid, cheaper"),
+    ],
+}
+
+
+def run_models(provider: Optional[str] = None):
+    from ..config import load_config
+
+    config = load_config()
+    print(f"Recommended models for profile: {config.profile}\n")
+    for model, role, cost in RECOMMENDED.get(config.profile, []):
+        print(f"- {model} | {role} | {cost}")
+
+    print("\nCurrent config:")
+    print(f"  Reasoning -> {config.models.reasoning}")
+    print(f"  Dev       -> {config.models.dev}")
+    print(f"  QA        -> {config.models.qa}")
+
+    print("\nAll available models (from opencode):")
+    try:
+        command = ["opencode", "models"]
+        if provider:
+            command.extend(["--provider", provider])
+        result = subprocess.run(command, capture_output=True, text=True, timeout=10)
+        if result.returncode == 0:
+            print(result.stdout)
+        else:
+            print("Run `opencode auth login` to configure providers.")
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        print("opencode not installed or not responding.")
+        print("Install: npm install -g opencode")
+

karajan/commands/profiles.py

@@ -0,0 +1,23 @@
+"""List profiles."""
+
+from __future__ import annotations
+
+from ..config import _load_profile, list_profiles
+
+
+def run_profiles():
+    print("Available profiles:\n")
+    for profile_name in list_profiles():
+        data = _load_profile(profile_name)
+        meta = data.get("meta", {})
+        models = data.get("models", {})
+        observability = data.get("observability", {})
+        print(f"{profile_name} - {meta.get('description', '')}")
+        print(f"  Tracker: {meta.get('tracker', '—')}")
+        print(f"  Dev CLI: {meta.get('dev_cli', '—')}")
+        print(f"  Reasoning: {models.get('reasoning', '—')}")
+        print(f"  Dev model: {models.get('dev', '—')}")
+        print(f"  QA model: {models.get('qa', '—')}")
+        print(f"  Observability: {observability.get('enabled', False)}")
+        print()
+

karajan/commands/status.py

@@ -0,0 +1,50 @@
+"""Show active workflows."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+STAGE_EMOJI = {
+    "research": "🔍",
+    "plan": "🏗️",
+    "hitl_plan": "👤",
+    "prd": "📝",
+    "hitl_prd": "👤",
+    "dev": "💻",
+    "review": "🔎",
+    "qa": "🧪",
+    "hitl_pr": "👤",
+    "done": "✅",
+}
+
+
+def run_status(ticket: Optional[str] = None):
+    state_dir = Path(".workflow-state")
+    if not state_dir.exists():
+        print("No active workflows")
+        return
+
+    state_files = list(state_dir.glob("*.json"))
+    if ticket:
+        state_files = [path for path in state_files if ticket.lower() in path.stem.lower()]
+
+    if not state_files:
+        print("No active workflows")
+        return
+
+    print("Active Workflows")
+    for state_file in sorted(state_files):
+        try:
+            state = json.loads(state_file.read_text(encoding="utf-8"))
+        except Exception:
+            print(f"{state_file.stem}: unknown")
+            continue
+        ticket_id = state.get("ticket_id", state_file.stem)
+        stage = state.get("current_stage", "unknown")
+        summary = state.get("ticket", {}).get("summary", "")
+        emoji = STAGE_EMOJI.get(stage, "⚙️")
+        print(f"{ticket_id} | {emoji} {stage} | {summary[:50]}")
+