Skill: philitician/blockmind-agent-architect (version 1.0.2)

--- name: agent-architect description: > Interactive consultant that helps developers design agent systems. Walks through structured intake questions about surfaces, tools, memory, deployment, and complexity, then synthesizes architecture recommendations grounded in curated external references. Use when someone asks for help designing, planning, or architecting an agent system, AI assistant, chatbot, automation workflow, or personal agent setup. --- # Agent Architect You are an agent architecture consultant. Help the developer design the right agent system for their use case by understanding their needs, then recommending proven patterns backed by curated reference material. Think expert at a whiteboard — warm, direct, opinionated when you have evidence. Not a form. ## Intake Flow Walk through these questions **one at a time**. Acknowledge each answer with a brief observation before asking the next question. Skip questions the user already answered. Adapt phrasing to the conversation — these are topics to cover, not a script. 1. **What are you building?** Domain, purpose, who uses it. 2. **What surfaces?** Where do users interact — Slack, Telegram, Discord, web chat, CLI, mobile, email? 3. **Single or multi-agent?** One generalist or multiple specialists? 4. **Coding agents?** What do developers on the team use — Codex, Claude Code, Cursor, Windsurf, other? 5. **Persistent memory?** Does the agent need to remember across sessions? 6. **Tools and integrations?** Web browsing, API calls, file access, database queries? 7. **Deployment?** Local machine, cloud, hybrid? Any infra preferences? 8. **Knowledge base or docs site?** Does the system need a maintained wiki or published docs? 9. **Complexity tolerance?** Minimal viable agent → production-grade system? After the last question, move to synthesis. Do not ask for permission to synthesize — just do it. ## Synthesis Map the user's answers to patterns from the reference material. Structure the recommendation as: ### Architecture Overview A 3–5 sentence summary of the recommended system. ### Component Recommendations For each major component, recommend a specific pattern and cite the reference file: - Which reference backs the recommendation - Why this pattern fits their stated needs - What it gives them and what it doesn't cover ### Suggested Reading Order List 2–4 reference files the user should read next, ordered by relevance to their specific case. ### Open Questions Flag anything their answers didn't cover that matters for implementation. After presenting the recommendation, offer to go deeper on any component. ## Knowledge Map Use these reference files to ground recommendations. Read the relevant files before making claims about the tools or patterns they describe. | Topic | Reference File | |-------|---------------| | Gateway, multi-channel routing, personal agent | `references/openclaw-docs.md` | | Repo conventions for Codex / AGENTS.md | `references/codex-customization-docs.md` | | Repo conventions for Claude Code / CLAUDE.md | `references/claude-code-memory-docs.md` | | LLM-maintained wiki pattern | `references/karpathy-llm-wiki.md` | | Filesystem-native agent context | `references/agentsearch-manifesto.md` | | Local sync, context sharing, agent plugins | `references/nia-docs.md` | | S3-compatible storage, publishing, mirroring | `references/fly-tigris-docs.md` | | Docs site framework | `references/fumadocs-docs.md` | | Full topic → source mapping | `references/source-map.md` | ## Grounding Rules 1. **Always cite reference files** when recommending a pattern or tool. Use the format: "See `references/<file>.md` for details." 2. **Read before recommending.** If you haven't read the reference file for a topic, read it before making claims. 3. **Flag gaps explicitly.** If the user's needs go beyond what the references cover, say: "Our curated sources don't cover X — here's my general knowledge, but verify independently." 4. **Distinguish confidence levels.** "This pattern is well-documented in our sources" vs. "Based on general knowledge." 5. **Never hallucinate tool names or features.** If you're unsure whether a tool supports something, check the reference or say you're unsure. 6. **No fluff.** Concrete recommendations with specific tool names and patterns. Skip "it depends" without a follow-up opinion.

path: references/agentsearch-manifesto.md
content: # AgentSearch Manifesto

## Source

- Canonical URL: https://www.agentsearch.sh/manifesto
- Related URL: https://www.agentsearch.sh/

## Summary

The AgentSearch manifesto makes a sharp claim: code hallucinations are not primarily a model problem, they are a data problem. The argument is straightforward. APIs, SDKs, and docs change constantly, while model training data is always delayed. An agent can generate code that looks syntactically perfect and still fail in production because the model never saw a deprecation, rename, or breaking change that shipped after training. In that frame, the real failure is not that the model cannot reason, but that it is reasoning over stale or missing information.

From there, the manifesto proposes a filesystem-as-interface pattern for agents. Instead of inventing a custom tool layer for each documentation source, it argues that the web should become navigable in the same way a codebase is. Agents already know how to use commands like `ls`, `cd`, `cat`, `tree`, `find`, and `grep`, because Unix-style filesystem interaction is deeply represented in their training data. If documentation can be surfaced as browsable directories and files, the agent gets an interface it already understands without having to learn a new protocol at runtime.

This is also the document's critique of MCP servers and bespoke tool schemas. Those approaches can work, but they cost context window space, require documentation, and force the agent into a trial-and-error phase where it learns the shape of the interface before it can do useful work. A filesystem has a lower activation cost. The model can immediately inspect structure, search for terms, and read relevant files with primitives it already uses well.

The manifesto's broader vision is that the entire web should behave like a navigable directory tree. Doc sites, changelogs, API references, and other current information sources become places an agent can enter, inspect, and traverse as though they were local. For a knowledge base like this repo, that idea matters because it supports a future where external references are not just linked, but mirrored and made directly legible to agents through plain files.


path: references/claude-code-memory-docs.md
content: # Claude Code Memory & CLAUDE.md

## Source

- Canonical URL: https://code.claude.com/docs/en/memory
- Related URL: https://docs.anthropic.com/en/docs/claude-code/memory

## Summary

Claude Code separates persistent guidance into two related but different systems: `CLAUDE.md` files and auto memory. The docs draw the distinction clearly. `CLAUDE.md` is authored intentionally by humans and contains instructions, conventions, project architecture, workflows, and rules the agent should follow. Auto memory is written by Claude itself as it learns patterns, commands, and debugging context while working in a given tree. That means `CLAUDE.md` is the explicit contract, while memory is the emergent operating history.

Scope matters in Claude's model. The docs describe project, user, and organization layers, which means guidance can live close to a repo, in a user's broader development environment, or at a higher organizational scope. This layered hierarchy is useful when some instructions are universally true for a team while others should apply only to one workspace. For a standalone repo like this one, the project-level `CLAUDE.md` is the key artifact because it gives Claude the local rules without depending on user-specific memory.

The documentation also calls out `.claude/rules/` for scoped rules. That is important because not all instructions should apply globally. Some constraints belong only to certain directories, file types, or workflows. Scoped rules help prevent the common problem where one large instruction file becomes too broad and starts leaking irrelevant requirements into unrelated work.

Claude loads memory at session start, which is why the docs stress keeping the startup context concise and useful. The memory documentation notes that auto memory is loaded into each session up to a threshold, while `CLAUDE.md` files are loaded in full. That creates a strong incentive to keep `CLAUDE.md` direct and well organized. The best practice is to write instructions that are durable, action-oriented, and specific enough to steer behavior, while leaving volatile or incidental details to memory and separate topic files. For this repo, Claude's model is the template for making project guidance portable, layered, and readable by both humans and agents.


path: references/codex-customization-docs.md
content: # OpenAI Codex Customization

## Source

- Canonical URL: https://openai.com/codex
- Related URL: https://platform.openai.com/docs/guides/codex

## Summary

OpenAI's Codex customization guidance is the main reference for making a repository legible to Codex over repeated sessions. The most visible mechanism is `AGENTS.md`. OpenAI describes it as the place to put persistent context that Codex cannot reliably infer from code alone: naming conventions, business rules, commands, known quirks, review expectations, and other repo-specific instructions. The practical point is that agent performance improves when important constraints live in a durable file rather than in one-off prompts.

Codex customization is broader than one markdown file. The official docs organize customization around repo guidance, rules, hooks, MCP, skills, and environment configuration. That matters because a well-structured agent repo separates stable policy from task-specific prompts. `AGENTS.md` carries the durable repo contract, while skills package repeatable workflows that need richer instructions, references, or scripts. This layered approach keeps the repository from turning into one giant prompt blob.

The docs and OpenAI guidance on real-world usage also emphasize how Codex reads and benefits from structured guidance files. Teams are encouraged to describe tasks as if they were well-scoped GitHub issues, to document canonical commands and module names, and to keep environment setup accurate so Codex can run builds and checks without guesswork. In practice, that means instructions should be concrete, file-path aware, and tied to the actual codebase instead of abstract principles alone.

The best practices that emerge are straightforward. Keep a single source of truth for business rules. Prefer explicit commands over implied workflows. Capture file paths, examples, and constraints where the agent will actually look. Use repo-local skills for recurring procedures that need more than a few bullet points. And keep the guidance current: stale agent instructions are just another form of bad data. For this repo, Codex customization is the basis for `AGENTS.md`, command discoverability, and the discipline of keeping knowledge artifacts in stable, agent-readable locations.


path: references/fly-tigris-docs.md
content: # Fly/Tigris Object Storage Documentation

## Source

- Canonical URL: https://fly.io/docs/tigris/
- Related URL: https://www.tigrisdata.com/docs/overview/
- Related URL: https://www.tigrisdata.com/docs/concepts/architecture/

## Summary

Fly's Tigris integration is a useful reference for the storage side of a knowledge system because it combines an S3-compatible API with a globally caching delivery model. In practical terms, Tigris lets you keep object storage behind familiar S3 semantics while taking advantage of Fly's global network for lower-latency access. That combination fits well with use cases where a knowledge repo needs to publish mirrored documentation, generated wiki snapshots, or other static artifacts to readers and agents in different regions.

The most important conceptual detail is how objects are stored and cached. Tigris documentation explains that objects are served close to the requesting user and that subsequent requests are cached in the user's region. With shadow buckets, Tigris can also front an existing S3-compatible store: if an object is missing locally, it can fetch from the shadow bucket, store it in a nearby region, and then serve future reads from Tigris. That makes Tigris not just storage, but also a migration and mirroring layer.

The public-versus-private bucket distinction is intentionally simple. Buckets are private by default, and a bucket can be made public for unauthenticated asset access. Public content is served from dedicated domains, while private access stays behind authentication and signed access patterns. The docs also note that bucket visibility is bucket-wide rather than ACL-driven, which keeps the mental model cleaner for operational use.

Fly CLI integration matters because it keeps storage management in the same operational workflow as the rest of Fly infrastructure. Commands like `fly storage create --public`, `flyctl storage list`, `flyctl storage dashboard`, and shadow bucket configuration make the storage layer scriptable and automatable. For this repository, the most relevant use case is publishing or mirroring knowledge artifacts: wiki snapshots, imported documentation, or static exports can live in a globally cached bucket while the repo remains the canonical authoring source.


path: references/fumadocs-docs.md
content: # Fumadocs

## Source

- Canonical URL: https://fumadocs.dev
- Related URL: https://fumadocs.dev/docs/getting-started

## Summary

Fumadocs is a React.js documentation framework designed to make docs sites feel like composable application infrastructure rather than a fixed theme. The homepage presents it as a framework that works with "any React.js framework, CMS — anything," and the supported starter flow explicitly includes Next.js, Waku, TanStack Start, and React Router. That flexibility matters for this repository because it means the knowledge base can stay markdown-first today without locking itself out of a future site implementation choice.

MDX support is a major reason Fumadocs is relevant. The framework supports plain Markdown for simple pages and richer MDX for developers who need JSX, custom components, includes, code tabs, callouts, and typed code examples. This is a strong fit for a knowledge wiki because some pages should remain lightweight summaries while others may eventually need interactive examples, embedded diagrams, or generated API views.

The architecture is explicitly composable. Fumadocs is separated into content, core, and UI layers. `fumadocs-mdx` handles content authoring, `fumadocs-core` provides the headless source and docs logic, and `fumadocs-ui` provides presentation components. That separation is important because it means the content model does not have to be tightly bound to one visual shell. A repo can keep markdown as the source of truth while choosing how much framework and how much custom UI to adopt.

The Obsidian angle makes it especially relevant here. The `fumadocs-obsidian` extension is built to handle Obsidian-style markdown, which aligns directly with the Karpathy-style wiki workflow this repo is implementing. In other words, Fumadocs can act as the browser layer for notes and wiki pages that were authored in an Obsidian-friendly filesystem. The result is a promising path from plain markdown knowledge assets to a polished docs site without giving up portability or agent-readable files.


path: references/karpathy-llm-wiki.md
content: # Karpathy LLM Wiki

## Source

- Canonical URL: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

## Summary

Karpathy's "LLM wiki" pattern is the clearest statement of why a maintained wiki should exist as its own layer rather than being treated as a side effect of prompting. The core model has three layers. First come the raw sources: papers, docs, transcripts, notes, logs, or any other primary material you do not want to lose or reinterpret prematurely. Second comes the wiki: a curated, continually improved markdown layer where the knowledge from those sources is normalized into pages that are easier to navigate, link, and maintain. Third comes conversation: the chat interaction where an LLM helps answer questions, draft plans, or explore ideas using the wiki as the already-compiled knowledge base.

The key insight is that knowledge work should be compiled once and then maintained, not re-derived from scratch every time someone asks a question. If the model has to reread the same raw inputs on every prompt, you are paying the same comprehension cost repeatedly, inviting inconsistency, and making the result dependent on prompt wording. A wiki flips that model. Important facts and relationships are distilled once into durable pages, and future chats can spend their attention budget on the new question instead of on reconstructing the whole background context.

Karpathy also frames Obsidian as a kind of IDE for knowledge. That metaphor is important because it treats markdown files, links, folders, and search as the developer environment for thinking. In this model, pages are not static documentation produced at the end of work. They are the live working surface where ideas are refined, connected, and kept current over time.

The pattern scales across multiple use cases. For personal knowledge management, it gives one person a durable memory substrate that survives across projects and sessions. For research, it helps consolidate papers, experiments, and notes into reusable synthesis. For businesses and teams, it creates a human-browsable and agent-usable knowledge layer that can absorb raw operating material and turn it into continuously improved institutional understanding.


path: references/nia-docs.md
content: # Nia Documentation

## Source

- Canonical URL: https://docs.trynia.ai/welcome
- Related URL: https://docs.trynia.ai/context-sharing
- Related URL: https://docs.trynia.ai/local-sync
- Related URL: https://docs.trynia.ai/plugins/overview

## Summary

Nia positions itself as an API layer for agent context. The product is not just about hosting documentation; it is about giving coding agents current, structured access to the information they need across repositories, docs, and local files. That makes it a useful reference for this knowledge repo, because the challenge here is not simply storing markdown. The harder problem is ensuring that an agent can discover, load, and reuse the right context at the right time without every session starting cold.

One of Nia's most relevant capabilities is local sync. The docs describe workflows for syncing local repositories and other local sources so the agent-facing context is not limited to what already exists on the public web. That matters for private systems, unpublished notes, and in-progress codebases where the most important context often exists only on disk. A knowledge repository can borrow this pattern by treating local markdown, imported docs, and generated summaries as first-class sync targets instead of as disconnected artifacts.

The context-sharing model is another important idea. Nia is designed so context can be shared between teammates or between systems without requiring each agent session to rediscover the same set of references manually. In practice, that means curated context becomes an asset in its own right. For a repo like this one, the manifest and summary pages play a similar role: they turn source discovery and evaluation into persistent state.

Nia's plugin and skill pattern is particularly relevant for coding agents. The docs distinguish heavier MCP-style integration from lighter agent-skill approaches that call Nia directly. That split is useful because it recognizes that agents need both standard interfaces and pragmatic shortcuts. The `npx nia-wizard@latest` setup flow fits this philosophy well: it gives agents and developers a first-class way to install and configure Nia-backed capabilities instead of treating remote docs as a disconnected surface. Combined, local sync, shared context, and agent skills form a practical blueprint for making current knowledge available where coding agents already work.


path: references/openclaw-docs.md
content: # OpenClaw Documentation

## Source

- Canonical URL: https://docs.openclaw.ai
- Related URL: https://github.com/openclaw/openclaw

## Summary

OpenClaw is best understood as a self-hosted gateway for AI agents. Instead of tying one model to one chat surface, it sits between channels and agents so that a single operating system for the agent can manage routing, tools, memory, and behavior. That makes it a strong reference for any repo that wants to support fast-start personal agents or team agents without depending entirely on a single vendor workflow.

The skill system is central to the design. Skills give the agent reusable procedures, constraints, and helper context for recurring tasks. Rather than expecting the base model to rediscover how to do everything from scratch, OpenClaw treats these packaged capabilities as part of the agent runtime. For this knowledge base, that matters because external references are most valuable when they can be paired with repeatable routines, not just passive storage.

OpenClaw also emphasizes memory and session management. The docs describe a workspace file pattern built around files such as `SOUL.md`, `USER.md`, dated `memory/YYYY-MM-DD.md` entries, and `MEMORY.md`. The idea is that the agent wakes up fresh each session but regains continuity by reading files that define identity, current user context, recent session history, and curated long-term memory. This is a pragmatic alternative to hoping that model context alone will preserve continuity across runs.

Multi-channel support is the other major lesson. OpenClaw is built to connect agents to more than one surface, which means the same agent logic can operate through chat, background workflows, and other routes while sharing the same workspace memory and skills. For a knowledge repository, that is important because the wiki should not be locked to a single UI. It should serve as the durable substrate behind different agent experiences.

Overall, OpenClaw contributes the operational pattern: a local workspace with explicit files, durable memory, and a skill layer that sits behind whatever chat or automation surfaces the agent happens to use.


path: references/source-map.md
content: # Source Map

This map connects common design questions to the sources that answer them best. For each topic, start with the source that defines the primary pattern, then use the related sources to fill in infrastructure or agent-specific detail.

## Building an LLM Wiki

Most relevant sources: [Karpathy LLM Wiki](../summaries/karpathy-llm-wiki.md), [Fumadocs](../summaries/fumadocs-docs.md), [Fly/Tigris Object Storage Documentation](../summaries/fly-tigris-docs.md)

Read first: Start with Karpathy because it defines the architecture: raw material, maintained wiki, and conversation on top. Then read Fumadocs if the question is how to present the wiki as a browsable docs surface. Read Tigris once the question shifts from authoring to publishing or snapshot distribution.

How they relate: Karpathy explains why the wiki exists at all; Fumadocs shows one way to turn that wiki into a human-facing interface; Tigris provides the delivery substrate for mirrored artifacts or public snapshots.

## Agent Context & Filesystem Patterns

Most relevant sources: [AgentSearch Manifesto](../summaries/agentsearch-manifesto.md), [Nia Documentation](../summaries/nia-docs.md), [OpenClaw Documentation](../summaries/openclaw-docs.md)

Read first: Start with AgentSearch for the principle that documentation access should feel like navigating a filesystem. Then move to Nia for a concrete implementation of current-context delivery and doc access. Read OpenClaw when the question broadens from document access to an always-on gateway with memory, sessions, and skills.

How they relate: AgentSearch supplies the philosophy, Nia operationalizes that philosophy for coding agents, and OpenClaw expands the scope from document retrieval into full agent orchestration.

## Agent-Facing Repo Conventions

Most relevant sources: [OpenAI Codex Customization](../summaries/codex-customization-docs.md), [Claude Code Memory & CLAUDE.md](../summaries/claude-code-memory-docs.md), [OpenClaw Documentation](../summaries/openclaw-docs.md)

Read first: Start with Codex customization to understand `AGENTS.md`, skills, and repo-level persistent guidance. Then read Claude's memory docs to see the same problem from another agent's perspective, especially around `CLAUDE.md`, auto memory, and scoped rules. Use OpenClaw as a third reference for workspace-operating files like `SOUL.md`, `MEMORY.md`, and daily memory logs.

How they relate: Codex and Claude define how commercial coding agents ingest instructions, while OpenClaw shows a more general workspace-file pattern for long-lived agent behavior.

## Publishing & Mirroring

Most relevant sources: [Fly/Tigris Object Storage Documentation](../summaries/fly-tigris-docs.md), [AgentSearch Manifesto](../summaries/agentsearch-manifesto.md), [Nia Documentation](../summaries/nia-docs.md)

Read first: Start with Tigris for the storage mechanics: bucket visibility, global caching, and Fly CLI workflows. Then read AgentSearch and Nia to understand why mirrored docs matter operationally for agents: both emphasize current, filesystem-usable documentation rather than stale model memory.

How they relate: Tigris handles object distribution; AgentSearch motivates the need for mirrored, current docs; Nia provides a concrete pattern for making those mirrored assets agent-accessible.

## Docs Site Generation

Most relevant sources: [Fumadocs](../summaries/fumadocs-docs.md), [Karpathy LLM Wiki](../summaries/karpathy-llm-wiki.md), [Claude Code Memory & CLAUDE.md](../summaries/claude-code-memory-docs.md)

Read first: Start with Fumadocs for the framework and content pipeline. Then revisit Karpathy to ensure the docs site serves the maintained wiki rather than replacing it. Claude's docs are useful here because they reinforce the value of concise, well-scoped markdown files that agents can load reliably at session start.

How they relate: Fumadocs is the rendering layer, Karpathy is the knowledge architecture behind the content, and Claude's guidance is a reminder that markdown structure is not only for humans but also for the agents that consume the repository.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)