SocialSeed Tasker

A graph-based task management framework with hexagonal architecture, AI agent orchestration, code-as-graph analysis, RAG-powered reasoning, deterministic contracts, secrets management, and hardened CI/CD.

Quick Start

1. Start the Database

cd .agent && docker compose up -d

2. Configure Environment

cp .agent/configs/.env.example .agent/configs/.env
# Edit .agent/configs/.env with your settings

3. Verify Setup

# Check database health
curl http://localhost:8000/health

# List components
curl http://localhost:8000/api/v1/components

Operation Modes: Direct vs API

Tasker supports two operation modes to suit different workflows:

• Direct Mode (default): Direct connection to Neo4j via Bolt protocol → Ideal for local development
• API Mode: HTTP calls to FastAPI backend → Ideal for production and integrated testing

Both modes support all CLI commands with identical syntax. Switch modes by setting the TASKER_MODE environment variable:

# Direct mode (default)
tasker component list

# API mode
TASKER_MODE=api tasker component list
TASKER_MODE=api TASKER_API_URL=http://localhost:8888 tasker component list

Documentation:

• docs/cli_modes.md — Complete dual-mode guide with examples
• docs/dual_mode_setup.md — Setup troubleshooting for both modes
• docs/api_contract.md — REST API endpoint reference

Available CLI Commands

# Components
tasker component create <name> -p <project>
tasker component list
tasker component show <id>
tasker component update <id>
tasker component delete <id>

# Issues
tasker issue create <title> -c <component> -p <priority>
tasker issue list
tasker issue show <id>
tasker issue close <id>

# Dependencies
tasker dependency add <issue> --depends-on <dep>
tasker dependency chain <issue>
tasker dependency blocked -p <project>

# Analysis
tasker analyze root-cause <issue>
tasker analyze impact <issue>

# Code-as-Graph
tasker code-graph scan <path>
tasker code-graph find <symbol>
tasker code-graph prune
tasker code-graph gc

# RAG & Reasoning
tasker rag search "<query>"
tasker rag status
tasker reasoning log --issue <id> --thought <thought>
tasker reasoning list --issue <id>

# Tenants
tasker tenant-create --id <name> --config '<json>'
tasker tenant-list
tasker tenant-delete --id <name>

# Feature Flags
tasker flag-set --name <name> --value '<json>'
tasker flag-get --name <name>
tasker flag-list
tasker flag-delete --name <name>

# Secrets
tasker secret set --name <key> --value <value>
tasker secret get --name <key>
tasker secret delete --name <key>
tasker secret rotate --name <key> --policy <policy>

# Backup
tasker backup create
tasker backup list
tasker backup restore <timestamp>

# Server Management
tasker serve
tasker serve --port 9000
tasker restart
tasker restart --force

Standard Tooling (CLI Utilities)

# Changelog generation
python tools/release/changelogctl.py generate --from <ref> --to <ref> --out CHANGELOG.md

# Contract validation
python tools/contracts/contractctl.py run --provider http://localhost:8000 --spec openapi.json --out report.json

# Mock server
python tools/contracts/mockctl.py run --spec openapi.json --port 9000

# Secrets management
python tools/secrets/secretctl.py put --name <key> --file <path>
python tools/secrets/secretctl.py get --name <key>
python tools/secrets/secretctl.py delete --name <key>
python tools/secrets/secretctl.py rotate --name <key> --interval 30 --policy monthly

# Chaos scenarios
python tools/chaos/chaosctl.py run redis-flap
python tools/chaos/chaosctl.py list
python tools/chaos/chaosctl.py report

API Endpoints

Environment Variables

Docker Commands

# Start all services
docker compose up -d

# Start full stack with monitoring
docker compose -f compose/dev/api.yml up -d
docker compose -f compose/tools/chaos.yml up -d --build

# Check status
docker compose ps

# View logs
docker compose logs -f tasker-api

# Stop (data persists)
docker compose down

# Stop and remove data
docker compose down -v

CI/CD

# Run CI locally
./scripts/ci/run_local_pipeline.sh

# Sign artifacts
export RELEASE_GPG_PRIVATE_KEY="<base64-key>"
./scripts/ci/sign_artifact.sh dist/tasker-*.whl

Local Development

# Start dev services (Neo4j + CLI)
make dev-up

# Run unit tests
make test

# Run integration tests (requires services)
make integration

# Run the reproducible example
make example-run
# output written to examples/output.json

# Start API, Neo4j and Board
docker compose -f compose/dev/api.yml up -d

# Open the board
http://localhost:8080

# Open API docs
http://localhost:8000/docs

Testing

# Unit + domain + application tests
pytest tests/unit/ tests/domain/ tests/application/ -v

# With coverage
pytest tests/unit/ tests/domain/ tests/application/ --cov=socialseed_tasker --cov-report=term-missing

# Integration tests (requires Neo4j running)
pytest tests/integration/ -v -m integration

# CI pipeline smoke tests
pytest tests/ci/ -q

# Security scan
bandit -r src -lll
safety check --full-report

For AI Agents

This project is optimized for AI agent collaboration. All operational knowledge is stored in the .agent/ directory.

• Skills: Specialized capabilities in .agent/skills/.
• Workflows: Step-by-step guides in .agent/workflows/.
• Protocol: Rules of engagement in .agent/AGENT_GUIDE.md.

Quick Start for Agents:

1. Read .agent/project.md for context.
2. Read .agent/AGENT_GUIDE.md for protocol.
3. Follow .agent/workflows/implement-issue.md for tasks.

Generated by SocialSeed Tasker v1.0.0 — 325+ issues resolved