diff --git a/README.md b/README.md index 39a9afe..e0d28e3 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,7 @@ This repository contains the Agentic package workspace. | Package | Path | Purpose | |---|---|---| | `@tnezdev/agentic` | `packages/agentic` | Core primitives and CLI | - -Runtime packages will live beside the core package under `packages/`. +| `@tnezdev/agentic-runtime-local` | `packages/agentic-runtime-local` | Local runtime package | ## Development @@ -21,3 +20,10 @@ bun run build ``` The dogfood workspace still lives at `.agentic/`. Start with [`.agentic/ONRAMP.md`](.agentic/ONRAMP.md), then read [`packages/agentic/AGENTS.md`](packages/agentic/AGENTS.md) for core package architecture. + +## Examples + +- [`.agentic/`](.agentic/) is the project dogfood workspace — a persona, skills, workflow, tasks, and memories used to build Agentic itself. Read [`.agentic/ONRAMP.md`](.agentic/ONRAMP.md) for the maintainer flow. +- [`examples/second-brain/`](examples/second-brain/) is a user-mode example. It shows how an agent harness can use Agentic primitives to run second-brain workflows with persona activation, task pickup, workflow gates, and finalized artifacts. Memory is intentionally left for user space and custom adapters. + +The second-brain example includes its own [`AGENTS.md`](examples/second-brain/AGENTS.md) bootstrap file for harnesses. diff --git a/examples/second-brain/.agentic/artifacts/01KTC500000000000000000010/meta.json b/examples/second-brain/.agentic/artifacts/01KTC500000000000000000010/meta.json new file mode 100644 index 0000000..7a20383 --- /dev/null +++ b/examples/second-brain/.agentic/artifacts/01KTC500000000000000000010/meta.json @@ -0,0 +1,16 @@ +{ + "id": "01KTC500000000000000000010", + "type": "research-brief", + "title": "Visible Switch Options Research Seed", + "body_ref": "01KTC500000000000000000010/v1.md", + "version": 1, + "finalized": true, + "tags": [ + "second-brain", + "research", + "example", + "para:resource/agentic-examples" + ], + "created_at": "2026-06-05T16:00:00.000Z", + "updated_at": "2026-06-05T16:00:00.000Z" +} diff --git a/examples/second-brain/.agentic/artifacts/01KTC500000000000000000010/v1.md b/examples/second-brain/.agentic/artifacts/01KTC500000000000000000010/v1.md new file mode 100644 index 0000000..d3c7df9 --- /dev/null +++ b/examples/second-brain/.agentic/artifacts/01KTC500000000000000000010/v1.md @@ -0,0 +1,35 @@ +# Visible Switch Options Research Seed + +## Question + +What physical or software-visible switch options could support a private second-brain input workflow? + +## Why It Matters + +A second-brain system gets better when capture is low-friction and intentional. A visible switch can make mode changes explicit: capture, focus, do-not-disturb, or research intake. + +## Findings + +- The useful axis is not hardware versus software. It is whether the switch state is observable by the host runtime. +- A good switch should expose state, not just fire an event. Agents need to know the current mode after restarts. +- The example should not bake in a particular device. Agentic should model the research loop and durable output, while the host runtime owns device integration. + +## Tradeoffs + +- Hardware switches are tangible and reliable, but integration is host-specific. +- Software toggles are portable and easier to demo, but less physically salient. +- Calendar or focus-mode signals may already exist, but they can blur user intent with ambient context. + +## Recommendation + +For a public Agentic example, keep the switch question as seed content only. Demonstrate the reusable second-brain research loop, not a device-specific integration. + +## Sources Consulted + +- Example seed only. Replace with real source notes during a live research pass. + +## Follow-Up Questions + +- Which host runtime will observe switch state? +- Does the user need momentary events, durable state, or both? +- Should switch state become memory, dispatch context, or runtime-local state? diff --git a/examples/second-brain/.agentic/config.toml b/examples/second-brain/.agentic/config.toml new file mode 100644 index 0000000..7bc0051 --- /dev/null +++ b/examples/second-brain/.agentic/config.toml @@ -0,0 +1,12 @@ +# Agentic configuration for the second-brain example. + +adapter = "filesystem" + +[memory] +dir = ".agentic/memory" +default_tier = "L1" +dream_depth = "3" + +[workflow] +graphs_dir = ".agentic/workflows" +runs_dir = ".agentic/runs" diff --git a/examples/second-brain/.agentic/personas/researcher.md b/examples/second-brain/.agentic/personas/researcher.md new file mode 100644 index 0000000..3793a8d --- /dev/null +++ b/examples/second-brain/.agentic/personas/researcher.md @@ -0,0 +1,44 @@ +--- +name: researcher +description: Activate when turning an open question into a concise second-brain research brief +memory_tags: [second-brain, research] +skills: [research-brief, project-kickoff] +task_filter: + tags: [research] + status: ready +workflow: research-loop +effort: medium +reasoning: high +--- + +# Second-Brain Researcher + +You are maintaining a second-brain research workspace from `{{cwd}}` on `{{hostname}}`. +The current time is `{{timestamp}}`. + +## Operating Principles + +- Start by restating the question and the decision it supports. +- Prefer durable findings over exhaustive notes. +- Separate evidence, interpretation, and recommendation. +- Preserve uncertainty. If a source is weak, say so. +- Write the output as an artifact that can be read later without the transcript. + +## Before Research + +1. Check `task next` for the active research question. +2. Run the `research-brief` skill for the work procedure. +3. If user memory is configured, recall relevant context tagged `second-brain` and `research`. +4. Use the `research-loop` workflow when the question spans more than one pass. + +## Output Shape + +Produce a brief with: + +- Question +- Why it matters +- Findings +- Tradeoffs +- Recommendation +- Sources consulted +- Follow-up questions diff --git a/examples/second-brain/.agentic/skills/project-kickoff/skill.md b/examples/second-brain/.agentic/skills/project-kickoff/skill.md new file mode 100644 index 0000000..87502c3 --- /dev/null +++ b/examples/second-brain/.agentic/skills/project-kickoff/skill.md @@ -0,0 +1,76 @@ +--- +name: project-kickoff +description: Activate when an agent needs to turn a project idea into a scoped PARA project without guessing the user's intent +tags: [second-brain, project, para, intake] +--- + +# Project Kickoff + +Use this procedure when the user wants to start or shape a project in a second-brain workspace. + +## Principles + +- Organize by actionability. A project exists to support a concrete outcome, not to classify information by broad subject. +- A project is a short-term effort with a goal. If it has no finish line, it is probably an area, resource, or habit instead. +- Do not draft a project plan from a title alone. First gather enough intent to avoid creating plausible but wrong tasks. +- Keep the first plan lightweight. The goal is clarity and movement, not a perfect system. +- End with the next essential step, not an exhaustive backlog. + +## Intake First + +Before creating a `project-plan` artifact, ask concise questions. Prefer 3-5 questions at a time. + +Ask about: + +- Outcome: What should be true when this project is done? +- Motivation: Why does this matter now? +- Scope: What is in bounds, and what is explicitly out of bounds for the first pass? +- Constraints: Are there deadlines, tools, people, budgets, or standards to respect? +- Current state: What already exists, and where is the messy input coming from? +- Success criteria: How will we know this worked? +- First useful action: What would create momentum without overbuilding? + +If the user already gave enough context, summarize your assumptions and ask for confirmation before creating durable artifacts. If the user explicitly asks for a speculative draft, label assumptions clearly. + +## PARA Placement + +Choose a concrete project bucket tag: + +```text +para:project/ +``` + +If the work is ongoing with no completion point, suggest an area tag instead: + +```text +para:area/ +``` + +If it is reference material without an active outcome, suggest a resource tag: + +```text +para:resource/ +``` + +## Project Plan Artifact + +After intake, write a `project-plan` artifact with: + +- Outcome +- Why It Matters +- Success Criteria +- Scope +- Constraints +- Current State +- PARA Bucket +- Milestones or Intermediate Packets +- Risks +- Current Next Actions + +Every project plan must include a `para:project/` tag unless the intake reveals it is not actually a project. + +## Next Actions + +Next actions should respect dependencies. Do not choose a later action if an earlier structure does not exist yet. + +For example, if the project is to create a reading queue, do not pick the first reading item until the queue surface, fields, and statuses exist. The better next action is to define the queue shape from the user's requirements. diff --git a/examples/second-brain/.agentic/skills/research-brief/skill.md b/examples/second-brain/.agentic/skills/research-brief/skill.md new file mode 100644 index 0000000..25abd94 --- /dev/null +++ b/examples/second-brain/.agentic/skills/research-brief/skill.md @@ -0,0 +1,50 @@ +--- +name: research-brief +description: Activate when an agent needs to convert a research question into a cited second-brain brief +tags: [second-brain, research, artifact] +--- + +# Research Brief + +Use this procedure when the task is to answer a research question for later reuse. + +## Procedure + +1. Restate the question in one sentence. +2. Identify the decision or action the answer should support. +3. Gather a small set of high-signal sources. Prefer primary sources, official docs, source code, standards, and direct measurements. +4. Extract findings as claims with source references. Do not preserve raw browsing notes unless they are necessary evidence. +5. Synthesize tradeoffs. Call out uncertainty and missing information. +6. Write a brief artifact. Keep it readable without the transcript. +7. Validate that the artifact has at least one PARA bucket tag. +8. Finalize the artifact once taxonomy validation passes. +9. Add follow-up tasks only for unresolved questions that affect a decision. + +## Artifact Contract + +Write a `research-brief` artifact with these sections: + +- `Question` +- `Why It Matters` +- `Findings` +- `Tradeoffs` +- `Recommendation` +- `Sources Consulted` +- `Follow-Up Questions` + +Every artifact must include at least one PARA bucket tag in this form: + +```text +para:/ +``` + +Allowed buckets are `project`, `area`, `resource`, and `archive`. Choose the bucket that describes where the brief belongs in the user's second-brain system. + +Do not finalize the artifact until this tag is present. Finalization means the brief is durable output for this research pass, not that it can never be superseded. + +## Quality Bar + +- A reader can tell what changed in their understanding. +- Recommendation follows from the evidence. +- Sources are named clearly enough to revisit. +- Unknowns are explicit instead of hidden in confident prose. diff --git a/examples/second-brain/.agentic/tasks/01KTC500000000000000000001.json b/examples/second-brain/.agentic/tasks/01KTC500000000000000000001.json new file mode 100644 index 0000000..707681d --- /dev/null +++ b/examples/second-brain/.agentic/tasks/01KTC500000000000000000001.json @@ -0,0 +1,18 @@ +{ + "id": "01KTC500000000000000000001", + "description": "Research visible switch options for a private second-brain input workflow", + "status": "ready", + "tags": [ + "second-brain", + "research", + "example" + ], + "annotations": [ + { + "text": "Seed task for the public example. Replace with a real recurring research question in your own workspace.", + "timestamp": "2026-06-05T16:00:00.000Z" + } + ], + "created_at": "2026-06-05T16:00:00.000Z", + "updated_at": "2026-06-05T16:00:00.000Z" +} diff --git a/examples/second-brain/.agentic/workflows/monthly-review.json b/examples/second-brain/.agentic/workflows/monthly-review.json new file mode 100644 index 0000000..9b167af --- /dev/null +++ b/examples/second-brain/.agentic/workflows/monthly-review.json @@ -0,0 +1,69 @@ +{ + "id": "monthly-review", + "name": "Monthly review", + "description": "Review project portfolio, areas, resources, and goals at monthly cadence.", + "version": "1.0", + "nodes": [ + { + "id": "summarize-month", + "label": "Summarize month", + "description": "Summarize major outputs, decisions, changes, and unresolved tensions from the month.", + "artifact": { + "type": "monthly-summary", + "description": "Narrative summary of the month.", + "required": true, + "tags": ["second-brain", "review", "monthly"] + } + }, + { + "id": "review-portfolio", + "label": "Review portfolio", + "description": "Review active projects and areas for alignment, overcommitment, and stale commitments.", + "artifact": { + "type": "portfolio-review", + "description": "Monthly project and area portfolio review.", + "required": true, + "tags": ["second-brain", "project", "area"] + } + }, + { + "id": "promote-resources", + "label": "Promote resources", + "description": "Identify reusable notes, briefs, and references that should become resource bucket material.", + "artifact": { + "type": "resource-review", + "description": "Resources to promote, merge, prune, or revisit.", + "required": true, + "tags": ["second-brain", "resource"] + } + }, + { + "id": "choose-month-focus", + "label": "Choose month focus", + "description": "Choose the next month's priorities, constraints, and explicit not-now list.", + "artifact": { + "type": "monthly-plan", + "description": "Next month focus and planning decisions.", + "required": true, + "tags": ["second-brain", "review", "plan"] + } + }, + { + "id": "finalize-review", + "label": "Finalize review", + "description": "Finalize the monthly review artifact and update tasks or memories with durable decisions.", + "artifact": { + "type": "finalized-artifact-ref", + "description": "Reference to finalized monthly review and updates made.", + "required": true, + "tags": ["second-brain", "artifact", "memory", "tasks"] + } + } + ], + "edges": [ + { "from": "summarize-month", "to": "review-portfolio" }, + { "from": "review-portfolio", "to": "promote-resources" }, + { "from": "promote-resources", "to": "choose-month-focus" }, + { "from": "choose-month-focus", "to": "finalize-review" } + ] +} diff --git a/examples/second-brain/.agentic/workflows/process-inbox.json b/examples/second-brain/.agentic/workflows/process-inbox.json new file mode 100644 index 0000000..c5b639b --- /dev/null +++ b/examples/second-brain/.agentic/workflows/process-inbox.json @@ -0,0 +1,69 @@ +{ + "id": "process-inbox", + "name": "Process inbox", + "description": "Turn uncategorized captures into tasks, memories, artifacts, or PARA bucket placements.", + "version": "1.0", + "nodes": [ + { + "id": "collect-inbox", + "label": "Collect inbox", + "description": "Gather uncategorized notes, links, files, and reminders that need routing.", + "artifact": { + "type": "inbox-batch", + "description": "Batch of inbox items to process.", + "required": true, + "tags": ["second-brain", "inbox"] + } + }, + { + "id": "triage-items", + "label": "Triage items", + "description": "For each item, decide delete, defer, delegate, task, memory, artifact, or reference.", + "artifact": { + "type": "inbox-triage", + "description": "Triage decision for each inbox item.", + "required": true, + "tags": ["second-brain", "inbox", "triage"] + } + }, + { + "id": "assign-buckets", + "label": "Assign buckets", + "description": "Assign retained items to concrete PARA buckets using para:/ tags.", + "artifact": { + "type": "taxonomy-validation", + "description": "PARA bucket assignment for retained inbox items.", + "required": true, + "tags": ["second-brain", "taxonomy"] + } + }, + { + "id": "create-outputs", + "label": "Create outputs", + "description": "Create tasks, memories, or artifacts for retained items; discard or archive the rest.", + "artifact": { + "type": "inbox-output-summary", + "description": "Created tasks, memories, artifacts, and discarded items.", + "required": true, + "tags": ["second-brain", "tasks", "memory", "artifact"] + } + }, + { + "id": "close-batch", + "label": "Close batch", + "description": "Confirm the inbox batch is empty or only contains intentionally deferred items.", + "artifact": { + "type": "inbox-closeout", + "description": "Closeout note for the processed inbox batch.", + "required": true, + "tags": ["second-brain", "inbox"] + } + } + ], + "edges": [ + { "from": "collect-inbox", "to": "triage-items" }, + { "from": "triage-items", "to": "assign-buckets" }, + { "from": "assign-buckets", "to": "create-outputs" }, + { "from": "create-outputs", "to": "close-batch" } + ] +} diff --git a/examples/second-brain/.agentic/workflows/project-archive.json b/examples/second-brain/.agentic/workflows/project-archive.json new file mode 100644 index 0000000..df8b341 --- /dev/null +++ b/examples/second-brain/.agentic/workflows/project-archive.json @@ -0,0 +1,69 @@ +{ + "id": "project-archive", + "name": "Project archive", + "description": "Close a PARA project, preserve lessons, and move reusable material to the right long-term bucket.", + "version": "1.0", + "nodes": [ + { + "id": "review-outcome", + "label": "Review outcome", + "description": "Compare the project outcome against the original success criteria and current reality.", + "artifact": { + "type": "project-retrospective", + "description": "Outcome review, what shipped, what changed, and what did not happen.", + "required": true, + "tags": ["second-brain", "project", "review"] + } + }, + { + "id": "extract-lessons", + "label": "Extract lessons", + "description": "Capture durable lessons, reusable patterns, and warnings as memories or artifacts.", + "artifact": { + "type": "lessons-learned", + "description": "Reusable lessons from the project and suggested memory updates.", + "required": true, + "tags": ["second-brain", "memory"] + } + }, + { + "id": "reclassify-material", + "label": "Reclassify material", + "description": "Move or retag durable outputs into area, resource, or archive buckets.", + "artifact": { + "type": "taxonomy-validation", + "description": "PARA reclassification plan for project artifacts and references.", + "required": true, + "tags": ["second-brain", "taxonomy"] + } + }, + { + "id": "close-loops", + "label": "Close loops", + "description": "Mark completed tasks done, cancel obsolete tasks, and create follow-up tasks only for live commitments.", + "artifact": { + "type": "next-actions", + "description": "Task closure and remaining follow-up actions.", + "required": true, + "tags": ["second-brain", "tasks"] + } + }, + { + "id": "finalize-archive-note", + "label": "Finalize archive note", + "description": "Write and finalize the archive note with a para:archive/ or successor bucket tag.", + "artifact": { + "type": "archive-note", + "description": "Final project archive note suitable for future retrieval.", + "required": true, + "tags": ["second-brain", "archive"] + } + } + ], + "edges": [ + { "from": "review-outcome", "to": "extract-lessons" }, + { "from": "extract-lessons", "to": "reclassify-material" }, + { "from": "reclassify-material", "to": "close-loops" }, + { "from": "close-loops", "to": "finalize-archive-note" } + ] +} diff --git a/examples/second-brain/.agentic/workflows/project-kickoff.json b/examples/second-brain/.agentic/workflows/project-kickoff.json new file mode 100644 index 0000000..7359618 --- /dev/null +++ b/examples/second-brain/.agentic/workflows/project-kickoff.json @@ -0,0 +1,82 @@ +{ + "id": "project-kickoff", + "name": "Project kickoff", + "description": "Turn a project idea into a scoped PARA project with next actions and success criteria.", + "version": "1.0", + "nodes": [ + { + "id": "intake-questions", + "label": "Ask kickoff questions", + "description": "Ask the user enough questions to understand the project outcome, motivation, constraints, success criteria, and first useful next action. Do not draft the project plan from assumptions unless the user explicitly asks for a speculative draft.", + "type": "manual", + "artifact": { + "type": "project-intake", + "description": "User-provided answers or explicitly labeled assumptions from the kickoff interview.", + "required": true, + "tags": ["second-brain", "project", "intake"] + } + }, + { + "id": "define-outcome", + "label": "Define outcome", + "description": "State the desired outcome, why it matters, and what done looks like using the kickoff intake answers as source material.", + "artifact": { + "type": "project-outcome", + "description": "Project outcome, success criteria, and decision context.", + "required": true, + "tags": ["second-brain", "project"] + } + }, + { + "id": "choose-para-bucket", + "label": "Choose PARA bucket", + "description": "Assign the project to a concrete PARA project tag in the form para:project/.", + "artifact": { + "type": "taxonomy-validation", + "description": "Selected PARA project tag and rationale.", + "required": true, + "tags": ["second-brain", "taxonomy"] + } + }, + { + "id": "map-resources", + "label": "Map resources", + "description": "Identify related areas, resources, constraints, stakeholders, and reference material.", + "artifact": { + "type": "project-context", + "description": "Context map for the project: related areas/resources, constraints, and references.", + "required": true, + "tags": ["second-brain", "project", "resources"] + } + }, + { + "id": "create-project-plan", + "label": "Create project plan", + "description": "Write the project plan artifact with scope, milestones, risks, and next actions.", + "artifact": { + "type": "project-plan", + "description": "Durable project plan artifact tagged with para:project/.", + "required": true, + "tags": ["second-brain", "project", "plan"] + } + }, + { + "id": "seed-next-actions", + "label": "Seed next actions", + "description": "Create or update tasks for the first concrete next actions.", + "artifact": { + "type": "next-actions", + "description": "Initial task list or task updates for the project.", + "required": true, + "tags": ["second-brain", "tasks"] + } + } + ], + "edges": [ + { "from": "intake-questions", "to": "define-outcome" }, + { "from": "define-outcome", "to": "choose-para-bucket" }, + { "from": "choose-para-bucket", "to": "map-resources" }, + { "from": "map-resources", "to": "create-project-plan" }, + { "from": "create-project-plan", "to": "seed-next-actions" } + ] +} diff --git a/examples/second-brain/.agentic/workflows/research-loop.json b/examples/second-brain/.agentic/workflows/research-loop.json new file mode 100644 index 0000000..06ec9da --- /dev/null +++ b/examples/second-brain/.agentic/workflows/research-loop.json @@ -0,0 +1,81 @@ +{ + "id": "research-loop", + "name": "Second-brain research loop", + "description": "Turn an open question into a durable research brief and explicit follow-up tasks.", + "version": "1.0", + "nodes": [ + { + "id": "frame-question", + "label": "Frame question", + "description": "Restate the question, identify the decision it supports, and define what a useful answer must contain.", + "artifact": { + "type": "research-frame", + "description": "Question framing notes: decision, scope, constraints, and success criteria.", + "required": true, + "tags": ["second-brain", "research"] + } + }, + { + "id": "gather-sources", + "label": "Gather sources", + "description": "Collect a small set of high-signal sources and record why each source is credible or limited.", + "artifact": { + "type": "source-notes", + "description": "Source list with claims, links or locators, and quality notes.", + "required": true, + "tags": ["second-brain", "research", "sources"] + } + }, + { + "id": "write-brief", + "label": "Write brief", + "description": "Synthesize findings, tradeoffs, recommendation, and follow-up questions into a durable artifact.", + "artifact": { + "type": "research-brief", + "description": "Final research brief suitable for future recall.", + "required": true, + "tags": ["second-brain", "research", "brief"] + } + }, + { + "id": "validate-taxonomy", + "label": "Validate taxonomy", + "description": "Inspect the research-brief artifact metadata and confirm it includes at least one valid PARA bucket tag in the form para:/ before finalization.", + "artifact": { + "type": "taxonomy-validation", + "description": "Validation note naming the artifact id and the PARA tag that places it in the user's second-brain system.", + "required": true, + "tags": ["second-brain", "taxonomy"] + } + }, + { + "id": "finalize-brief", + "label": "Finalize brief", + "description": "Finalize the research-brief artifact after taxonomy validation passes so it becomes durable output for this research pass.", + "artifact": { + "type": "finalized-artifact-ref", + "description": "Reference to the finalized research-brief artifact.", + "required": true, + "tags": ["second-brain", "research", "artifact"] + } + }, + { + "id": "decide-next-actions", + "label": "Decide next actions", + "description": "Mark the task done if the brief supports the decision, or add specific follow-up tasks for remaining blockers.", + "artifact": { + "type": "next-actions", + "description": "Task updates or follow-up questions derived from the brief.", + "required": false, + "tags": ["second-brain", "tasks"] + } + } + ], + "edges": [ + { "from": "frame-question", "to": "gather-sources" }, + { "from": "gather-sources", "to": "write-brief" }, + { "from": "write-brief", "to": "validate-taxonomy" }, + { "from": "validate-taxonomy", "to": "finalize-brief" }, + { "from": "finalize-brief", "to": "decide-next-actions" } + ] +} diff --git a/examples/second-brain/.agentic/workflows/weekly-review.json b/examples/second-brain/.agentic/workflows/weekly-review.json new file mode 100644 index 0000000..dd1504d --- /dev/null +++ b/examples/second-brain/.agentic/workflows/weekly-review.json @@ -0,0 +1,69 @@ +{ + "id": "weekly-review", + "name": "Weekly review", + "description": "Review active commitments, recent outputs, and next-week focus across the second-brain workspace.", + "version": "1.0", + "nodes": [ + { + "id": "collect-inputs", + "label": "Collect inputs", + "description": "Gather open tasks, recent artifacts, calendar/context notes, and inbox items relevant to the week.", + "artifact": { + "type": "review-inputs", + "description": "Input summary for the weekly review.", + "required": true, + "tags": ["second-brain", "review", "weekly"] + } + }, + { + "id": "review-projects", + "label": "Review projects", + "description": "Scan active project buckets for stuck work, missing next actions, and completed outcomes.", + "artifact": { + "type": "project-review", + "description": "Project-by-project weekly review notes.", + "required": true, + "tags": ["second-brain", "project", "weekly"] + } + }, + { + "id": "review-areas", + "label": "Review areas", + "description": "Check active areas for maintenance issues, recurring obligations, and ignored standards.", + "artifact": { + "type": "area-review", + "description": "Area maintenance review and risks.", + "required": true, + "tags": ["second-brain", "area", "weekly"] + } + }, + { + "id": "choose-focus", + "label": "Choose focus", + "description": "Pick the next week's priority focus and name what will intentionally not be pursued.", + "artifact": { + "type": "weekly-plan", + "description": "Weekly focus, tradeoffs, and next actions.", + "required": true, + "tags": ["second-brain", "review", "plan"] + } + }, + { + "id": "finalize-review", + "label": "Finalize review", + "description": "Finalize the weekly review artifact with a valid PARA tag and update tasks.", + "artifact": { + "type": "finalized-artifact-ref", + "description": "Reference to finalized weekly review and task updates.", + "required": true, + "tags": ["second-brain", "artifact", "tasks"] + } + } + ], + "edges": [ + { "from": "collect-inputs", "to": "review-projects" }, + { "from": "review-projects", "to": "review-areas" }, + { "from": "review-areas", "to": "choose-focus" }, + { "from": "choose-focus", "to": "finalize-review" } + ] +} diff --git a/examples/second-brain/.agentic/workflows/yearly-review.json b/examples/second-brain/.agentic/workflows/yearly-review.json new file mode 100644 index 0000000..8f73e6a --- /dev/null +++ b/examples/second-brain/.agentic/workflows/yearly-review.json @@ -0,0 +1,69 @@ +{ + "id": "yearly-review", + "name": "Yearly review", + "description": "Synthesize the year, extract long-term lessons, and choose next-year direction.", + "version": "1.0", + "nodes": [ + { + "id": "collect-year", + "label": "Collect year", + "description": "Gather monthly reviews, major artifacts, completed projects, and meaningful area changes.", + "artifact": { + "type": "year-review-inputs", + "description": "Collected source material for yearly review.", + "required": true, + "tags": ["second-brain", "review", "yearly"] + } + }, + { + "id": "identify-themes", + "label": "Identify themes", + "description": "Find repeated patterns, compounding wins, recurring failures, and identity-level shifts.", + "artifact": { + "type": "yearly-themes", + "description": "Themes and lessons from the year.", + "required": true, + "tags": ["second-brain", "reflection", "yearly"] + } + }, + { + "id": "archive-completed-work", + "label": "Archive completed work", + "description": "Identify projects to archive and resources or memories to preserve for long-term use.", + "artifact": { + "type": "archive-plan", + "description": "Project archive and preservation plan.", + "required": true, + "tags": ["second-brain", "archive", "resource"] + } + }, + { + "id": "set-direction", + "label": "Set direction", + "description": "Choose next-year priorities, standards, and explicit non-goals.", + "artifact": { + "type": "yearly-plan", + "description": "Next-year direction and planning decisions.", + "required": true, + "tags": ["second-brain", "review", "plan"] + } + }, + { + "id": "finalize-review", + "label": "Finalize review", + "description": "Finalize the yearly review artifact and create follow-up projects or area standards.", + "artifact": { + "type": "finalized-artifact-ref", + "description": "Reference to finalized yearly review and resulting project/task updates.", + "required": true, + "tags": ["second-brain", "artifact", "tasks"] + } + } + ], + "edges": [ + { "from": "collect-year", "to": "identify-themes" }, + { "from": "identify-themes", "to": "archive-completed-work" }, + { "from": "archive-completed-work", "to": "set-direction" }, + { "from": "set-direction", "to": "finalize-review" } + ] +} diff --git a/examples/second-brain/AGENTS.md b/examples/second-brain/AGENTS.md new file mode 100644 index 0000000..6a3a258 --- /dev/null +++ b/examples/second-brain/AGENTS.md @@ -0,0 +1,103 @@ +# AGENTS.md — Second-Brain Example + +Use this file as the harness bootstrap for agents working in this example workspace. + +## What This Is + +This directory is an Agentic second-brain research workspace. Agentic provides the durable primitives; the harness provides the model call, tools, research access, and execution loop. + +Workspace base dir: + +```bash +examples/second-brain +``` + +## Start Here + +At the start of a research turn, activate the researcher persona: + +```bash +agentic persona activate researcher --base-dir examples/second-brain +``` + +Treat the output as operating context for the turn. Follow the persona's instructions. + +Then gather the current working context: + +```bash +agentic task next --base-dir examples/second-brain +agentic skill run research-brief --base-dir examples/second-brain +``` + +If this workspace has a user-provided memory adapter or seeded user memories, recall relevant context as well. This public example does not ship with memory records. + +If the installed `agentic` binary is unavailable while working from this repo, use: + +```bash +bun ../../packages/agentic/src/cli/main.ts persona activate researcher --base-dir . +bun ../../packages/agentic/src/cli/main.ts task next --base-dir . +bun ../../packages/agentic/src/cli/main.ts skill run research-brief --base-dir . +``` + +When running `project-kickoff`, load its skill before planning: + +```bash +agentic skill run project-kickoff --base-dir examples/second-brain +``` + +## How To Use Agentic + +- Use `persona activate` to load the hat and turn-level operating instructions. +- Use `skill run` to load reusable procedures. +- Use `memory recall` only when the user has configured memory records or an adapter for this workspace. +- Use `task next` to find the active research question. +- Use `workflow run` for multi-step research that needs resumable state. +- Use `artifact create`, `artifact write`, and `artifact finalize` for durable outputs. +- Finalize artifacts only after the workflow's taxonomy validation step passes. +- When a workflow step requires user intent that is not already available, ask concise questions before creating durable artifacts. Label any assumptions explicitly. + +## Boundary + +Agentic is not the harness. Do not expect it to browse, call a model, schedule work, manage auth, or execute approvals. + +The harness owns: + +- Model calls +- Tool execution +- Web or file research +- Credentials and authorization +- Scheduling and notifications +- Final user communication + +Agentic owns: + +- Personas +- Skills +- Memories when the user configures them +- Tasks +- Workflows +- Artifacts + +## Research Output + +When research produces a reusable answer, persist it as a `research-brief` artifact. Do not leave the final answer only in the transcript. + +Every artifact must include at least one PARA bucket tag: + +```text +para:/ +``` + +Allowed buckets are `project`, `area`, `resource`, and `archive`. The slug names the concrete bucket, such as `para:project/visible-switch-research`, `para:area/personal-finance`, or `para:resource/cellular-plans`. + +For multi-step research, use the `research-loop` workflow as the enforcement gate: write the brief, validate taxonomy, then finalize the artifact. Finalization means the artifact is durable output for this research pass. + +Use this shape: + +- Question +- Why It Matters +- Findings +- Tradeoffs +- Recommendation +- Sources Consulted +- Follow-Up Questions diff --git a/examples/second-brain/README.md b/examples/second-brain/README.md new file mode 100644 index 0000000..1f65f69 --- /dev/null +++ b/examples/second-brain/README.md @@ -0,0 +1,194 @@ +# Second-Brain Research Example + +This example shows Agentic as a small research operating system: personas, skills, workflows, a task queue, and finalized artifacts. + +It is intentionally personal-workflow shaped rather than product-demo shaped. The point is not to automate research end-to-end. The point is to give an agent enough durable structure to pick up a question, preserve useful findings, and produce a reusable brief without turning Agentic into a host runtime. + +## Big Picture + +Agentic is the primitive layer. It stores and loads the pieces an agent needs inside a turn, but it does not call the model or execute research by itself. + +In this example: + +- The harness reads `AGENTS.md` to learn how to enter the workspace. +- The harness activates the `researcher` persona and gives that output to the model. +- The agent uses `task next` and `skill run` to gather working context. +- The agent uses the `research-loop` workflow to keep multi-step research resumable. +- The agent writes the final answer as an artifact so the result survives beyond the transcript. + +The host harness still owns model calls, tool execution, browsing, credentials, approvals, scheduling, and user communication. + +## Try It + +From the repo root: + +```bash +bun src/cli/main.ts persona activate researcher --base-dir examples/second-brain +bun src/cli/main.ts skill run research-brief --base-dir examples/second-brain +bun src/cli/main.ts workflow list --base-dir examples/second-brain +bun src/cli/main.ts task next --base-dir examples/second-brain +bun src/cli/main.ts artifact list --base-dir examples/second-brain +``` + +After installing the package, replace `bun src/cli/main.ts` with `agentic`. + +Agent harnesses should start with [`AGENTS.md`](AGENTS.md). It contains the minimal bootstrap instructions for when and how to call Agentic primitives inside this workspace. + +## How The Pieces Work Together + +### Harness Bootstrap + +`AGENTS.md` is not an Agentic primitive. It is a harness convention: a short file that tells an agent how to use this workspace. + +It answers the questions a generic harness needs at startup: + +- Which base directory should Agentic commands use? +- Which persona should activate first? +- Which task and skill should be loaded? +- What is Agentic responsible for, and what does the harness still own? +- What must be true before an artifact is finalized? + +### Persona + +`.agentic/personas/researcher.md` is the agent's operating mode for this workspace. + +It declares: + +- `memory_tags`: which memories are relevant to recall. +- `skills`: which procedures are likely useful. +- `task_filter`: which tasks belong to this hat. +- `workflow`: the default workflow for this kind of work. +- Body text: the actual instructions rendered into context at activation time. + +Running `persona activate researcher` prints the rendered persona. A harness should treat that output as prompt/context for the turn. + +### Skill + +`.agentic/skills/research-brief/skill.md` is the reusable procedure for producing a research brief. + +It tells the agent how to move from open question to durable answer, including the expected artifact sections and the requirement to validate PARA taxonomy before finalization. + +Skills are loaded on demand. They keep repeated procedures out of a bloated always-on system prompt. + +### Memory + +Agentic supports memory, but this public example does not ship with `.agentic/memory/*.json` records. + +That is intentional. Memory is user-space: users may bring their own memories, storage adapters, and retention rules. A harness using this workspace can still call `memory recall` when user memory is configured, but the example itself keeps durable example output in artifacts. + +Memories are not a transcript. They are compact facts the user wants the agent to remember across sessions. + +### Task + +`.agentic/tasks/*.json` stores open work. + +The seeded task gives the agent a concrete research question to pick up. In a real second-brain workspace, tasks would be the research questions, decisions, or follow-ups that should not disappear between turns. + +### Workflow + +`.agentic/workflows/*.json` contains stateful processes for repeated second-brain operations. + +The research workflow is: + +```text +frame-question +→ gather-sources +→ write-brief +→ validate-taxonomy +→ finalize-brief +→ decide-next-actions +``` + +The important part is the review gate: + +- `write-brief` creates or updates the draft research artifact. +- `validate-taxonomy` confirms the artifact has a valid PARA bucket tag. +- `finalize-brief` finalizes the artifact only after validation passes. + +This is intentionally workflow-enforced rather than globally enforced by Agentic. Second-brain taxonomy rules are user- and workspace-specific, so the example encodes them in the workflow, skill, and harness instructions. + +This example also includes other common second-brain workflows: + +| Workflow | Use it when | +|---|---| +| `research-loop` | Turning an open question into a durable research brief | +| `project-kickoff` | Turning an idea into a scoped PARA project with next actions; starts with user intake questions | +| `project-archive` | Closing a project, preserving lessons, and reclassifying useful material | +| `weekly-review` | Reviewing active commitments and choosing next-week focus | +| `monthly-review` | Reviewing the project/area/resource portfolio and choosing next-month focus | +| `yearly-review` | Synthesizing the year and choosing next-year direction | +| `process-inbox` | Routing uncategorized captures into tasks, memories, artifacts, or PARA buckets | + +### Artifact + +`.agentic/artifacts/*` stores durable outputs. + +The seed artifact is a finalized `research-brief`. It demonstrates the expected output shape and the required PARA tag convention: + +```text +para:/ +``` + +Allowed buckets are: + +- `project` +- `area` +- `resource` +- `archive` + +Example tags: + +- `para:project/visible-switch-research` +- `para:area/personal-finance` +- `para:resource/cellular-plans` +- `para:archive/old-research` + +Finalization means the artifact is durable output for this research pass. It does not mean the answer can never be superseded. + +## What Is In Here + +| Path | Primitive | Purpose | +|---|---|---| +| `AGENTS.md` | Harness bootstrap | Minimal instructions for agents using this workspace | +| `.agentic/personas/researcher.md` | Persona | Activates the research hat: question-first, source-aware, concise synthesis | +| `.agentic/skills/research-brief/skill.md` | Skill | Agent-facing procedure for turning a question into a cited brief | +| `.agentic/skills/project-kickoff/skill.md` | Skill | Agent-facing procedure for interviewing before drafting a project plan | +| `.agentic/workflows/*.json` | Workflow | Research, project, review, archive, and inbox operating loops | +| `.agentic/tasks/*.json` | Tasks | A real ready task seeded with an example research question | +| `.agentic/artifacts/*` | Artifact | A finalized sample brief showing the target output | + +## Dogfooding Loop + +To dogfood this example, use it for one real research question and watch for friction. + +1. Activate the persona. +2. Load the task and skill. +3. Start or inspect a `research-loop` workflow run. +4. Do the research using whatever tools the harness provides. +5. Create or update a `research-brief` artifact. +6. Validate that the artifact has a `para:/` tag. +7. Finalize the artifact. +8. Mark the task done or add follow-up tasks. + +Good dogfood findings are not just better answers. They are also places where the primitive boundaries feel wrong, missing, or too ceremonial. + +## Why This Shape + +Second-brain work repeats. The questions change, but the operating shape stays stable: + +- Activate a persona so the agent knows how to think. +- Run a skill so the work procedure is explicit and reusable. +- Advance a workflow so multi-step work has state. +- Track tasks so open loops do not disappear. +- Write artifacts so the output becomes durable and inspectable. + +Agentic owns those primitives. Your host runtime still owns browsing, credentials, model calls, scheduling, approvals, and notification surfaces. + +## Extending It + +Use this as a starter shape, not a template to preserve exactly. + +- Add memories for your own source standards, output preferences, and active research areas. +- Add skills for recurring research genres: literature review, product comparison, meeting prep, or decision memo. +- Add workflow nodes only when they represent real state you need to resume later. +- Keep artifacts as the durable outputs; do not rely on a transcript as the source of truth.