chore: add LICENSE, README, update package.json and AGENTS.md for npm release prep
This commit is contained in:
114
AGENTS.md
114
AGENTS.md
@@ -1,60 +1,86 @@
|
||||
## Memory Tools (via @alkdev/open-memory plugin)
|
||||
# @alkdev/flowgraph — Agent Guide
|
||||
|
||||
You have access to two tools for managing your context and accessing session history:
|
||||
Project-specific context for AI agents working on this codebase.
|
||||
|
||||
### memory({tool: "...", args: {...}})
|
||||
## What This Is
|
||||
|
||||
Read-only tool for introspecting your session history and context state. Available operations:
|
||||
- `memory({tool: "help"})` — full reference with examples
|
||||
- `memory({tool: "summary"})` — quick counts of projects, sessions, messages, todos
|
||||
- `memory({tool: "sessions"})` — list recent sessions (useful for finding past work)
|
||||
- `memory({tool: "children", args: {sessionId: "ses_..."}})` — list sub-agent sessions spawned from a parent
|
||||
- `memory({tool: "messages", args: {sessionId: "..."}})` — read a session's conversation
|
||||
- `memory({tool: "messages", args: {sessionId: "...", role: "assistant"}})` — read only assistant messages
|
||||
- `memory({tool: "messages", args: {sessionId: "...", showTools: true}})` — include tool-call output
|
||||
- `memory({tool: "message", args: {messageId: "msg_..."}})` — read a single message by ID
|
||||
- `memory({tool: "search", args: {query: "..."}})` — search across all conversations
|
||||
- `memory({tool: "compactions", args: {sessionId: "..."}})` — view compaction checkpoints
|
||||
- `memory({tool: "context"})` — check your current context window usage
|
||||
DAG-based workflow orchestration library. Wraps graphology `DirectedGraph`, enforces DAG invariants, provides ujsx template composition and reactive signal-driven execution. Sits between `@alkdev/operations` (what can be called) and `@alkdev/alkhub` (what was called) — defines *how calls are orchestrated*.
|
||||
|
||||
### memory_compact()
|
||||
## Build & Test Commands
|
||||
|
||||
Trigger compaction on the current session. This summarizes the conversation so far to free context space.
|
||||
```bash
|
||||
npm run build # tsup (ESM + CJS + dts + sourcemaps)
|
||||
npm run build:tsc # tsc type-check only
|
||||
npm run lint # tsc --noEmit
|
||||
npm run test # vitest run
|
||||
npm run test:watch # vitest watch
|
||||
npm run test:coverage # vitest run --coverage
|
||||
```
|
||||
|
||||
**When to use memory_compact:**
|
||||
- When context is above 80% (check with `memory({tool: "context"})`)
|
||||
- When you notice you're losing track of earlier conversation details
|
||||
- At natural breakpoints in multi-step tasks (after completing a subtask, before starting a new one)
|
||||
- When the system prompt shows a yellow/red/critical context warning
|
||||
- Proactively, rather than waiting for automatic compaction at 92%
|
||||
Always run `npm run lint && npm run test` after making changes.
|
||||
|
||||
**When NOT to use memory_compact:**
|
||||
- When context is below 50% (it wastes a compaction cycle)
|
||||
- In the middle of a complex edit that you need immediate context for
|
||||
- When the task is nearly complete (just finish the task instead)
|
||||
## Source Structure
|
||||
|
||||
Compaction preserves your most important context in a structured summary — you will continue the session with the summary as your starting point.
|
||||
```
|
||||
src/
|
||||
index.ts # Barrel — re-exports all sub-modules
|
||||
component/ # ujsx workflow components (Operation, Sequential, Parallel, Conditional, Map)
|
||||
host/ # HostConfig implementations (GraphologyHostConfig, ReactiveHostConfig)
|
||||
schema/ # TypeBox schemas, enums, node/edge attribute types
|
||||
graph/ # FlowGraph class (construction, mutation, query, serialization)
|
||||
reactive/ # WorkflowReactiveRoot, signal-driven status, event log projection
|
||||
analysis/ # Pure functions: typeCompat, validate, topologicalOrder, parallelGroups, criticalPath
|
||||
error/ # FlowgraphError hierarchy
|
||||
```
|
||||
|
||||
## Worktree Tool (via @alkimiadev/open-coordinator plugin)
|
||||
## Subpath Exports
|
||||
|
||||
You have access to the `worktree` tool for git worktree management and session coordination. Call with `{action, args}`:
|
||||
The package has 8 export subpaths. Root `@alkdev/flowgraph` re-exports everything. Subpath imports make dependencies explicit:
|
||||
|
||||
### Coordinator Operations (available when session is not spawned by another session)
|
||||
| Subpath | Key Exports |
|
||||
|---------|-------------|
|
||||
| `/graph` | `FlowGraph`, `FlowGraphOptions`, `OperationSpec`, `CallEventMapValue` |
|
||||
| `/schema` | `CallStatus`, `NodeStatus`, `EdgeType`, `OperationType`, all node/edge attribute types |
|
||||
| `/component` | `Operation`, `Sequential`, `Parallel`, `Conditional`, `Map` |
|
||||
| `/host` | `GraphologyHostConfig`, `ReactiveHostConfig` |
|
||||
| `/analysis` | `typeCompat`, `buildTypeEdges`, `validateGraph`, `validateSchema`, `validate`, `validateTemplate`, `topologicalOrder`, `parallelGroups`, `criticalPath` |
|
||||
| `/reactive` | `WorkflowReactiveRoot`, `EventLogProjection`, `WorkflowNode`, `FailurePolicy` |
|
||||
| `/error` | `FlowgraphError`, `ConstructionError`, `CycleError`, `InvalidInputError`, `InvalidTransitionError` |
|
||||
|
||||
- `worktree({action: "list"})` — List git worktrees
|
||||
- `worktree({action: "dashboard"})` — Worktree dashboard with session info
|
||||
- `worktree({action: "spawn", args: {tasks: [...], prompt: "..."}})` — Spawn parallel worktrees + sessions
|
||||
- `worktree({action: "sessions"})` — Query spawned session status
|
||||
- `worktree({action: "message", args: {sessionID: "...", message: "..."}})` — Message a session
|
||||
- `worktree({action: "abort", args: {sessionID: "..."}})` — Abort a session
|
||||
- `worktree({action: "cleanup", args: {action: "remove", pathOrBranch: "..."}})` — Remove worktree
|
||||
- `worktree({action: "help"})` — Show all available operations
|
||||
## Key Patterns
|
||||
|
||||
### Implementation Operations (available when session is spawned by a coordinator)
|
||||
- **TypeBox schema + Static type pairs**: Every schema is exported as both a const (runtime) and an inferred type. `const FooSchema = Type.Object({...}); type Foo = Static<typeof FooSchema>;`
|
||||
- **Delegation model**: `FlowGraph` wraps a graphology `DirectedGraph` (does not extend it). `flowGraph.graph` is an escape hatch that bypasses validation.
|
||||
- **DAG enforcement**: `addEdge()` throws `CycleError` if the edge would create a cycle. `fromJSON()` validates DAG invariants on deserialization.
|
||||
- **Event log as source of truth**: Call protocol events (`call.requested`, `call.responded`, `call.error`, `call.aborted`, `call.completed`) are appended to `WorkflowReactiveRoot`. Status/results are derived projections.
|
||||
- **Signal-driven execution**: `@preact/signals-core` powers `WorkflowReactiveRoot`. `preconditions`, `canStart`, `blockedByFailure` are `ReadonlySignal<boolean>` computed from predecessor status.
|
||||
- **`dispose()` is mandatory**: `WorkflowReactiveRoot.dispose()` must be called to release signal subscriptions.
|
||||
|
||||
- `worktree({action: "current"})` — Show your worktree mapping
|
||||
- `worktree({action: "notify", args: {message: "...", level: "info|blocking"}})` — Report to coordinator
|
||||
- `worktree({action: "status"})` — Show worktree git status
|
||||
## Architecture Docs
|
||||
|
||||
The plugin auto-injects `workdir` for bash commands when the session is mapped to a worktree.
|
||||
`docs/architecture/` contains detailed specs (all `status: reviewed`):
|
||||
|
||||
- `README.md` — overview, relationship to sibling packages, design decisions
|
||||
- `flowgraph-api.md` — FlowGraph class full API
|
||||
- `consumer-integration.md` — end-to-end integration walkthrough (5 phases)
|
||||
- `schema.md` — TypeBox Module, all node/edge attribute schemas
|
||||
- `operation-graph.md` — static graph from OperationSpecs
|
||||
- `call-graph.md` — dynamic graph from call events
|
||||
- `workflow-templates.md` — ujsx components, composition rules, template→DAG hydration
|
||||
- `host-configs.md` — GraphologyHostConfig, ReactiveHostConfig
|
||||
- `reactive-execution.md` — signal-driven status propagation, lifecycle, error boundaries
|
||||
- `analysis.md` — type-compatibility checking, precondition validation, execution ordering
|
||||
- `error-handling.md` — FlowgraphError hierarchy
|
||||
- `build-distribution.md` — package structure, exports map
|
||||
- `decisions/` — ADRs 001–006
|
||||
|
||||
Consult these for anything non-trivial. The README is surface-level; architecture docs are the specification.
|
||||
|
||||
## Constraints for Agent Modifications
|
||||
|
||||
- **Never add cycles** — this is a DAG-only library. Any edge that would create a cycle must throw `CycleError`.
|
||||
- **Never mutate operation graphs after construction** — `fromSpecs()` graphs are conventionally immutable.
|
||||
- **Keep schema as pure data** — `src/schema/` contains TypeBox schemas and types only, no runtime logic.
|
||||
- **Keep analysis as pure functions** — `src/analysis/` functions take a `FlowGraph` or `DirectedGraph` as input and return results without side effects.
|
||||
- **Maintain the delegation model** — `FlowGraph` delegates to graphology. Don't expose raw graphology methods that could violate DAG invariants without explicit validation.
|
||||
- **tsup builds all subpath entries** — `tsup.config.ts` lists every subpath. If you add a new top-level module, add the entry there and update `package.json` exports.
|
||||
Reference in New Issue
Block a user