personal-agent-architect

Overview

Personal Agent Architect builds a person a matched personalization set from their own Amazon Quick environment: a personal voice-and-preference skill, a space preloaded with the data they use often, and a lightweight agent wired to both. It reads what is already true about the person (memories, knowledge graph, past conversations, installed skills, connectors, frequently-used data) rather than interrogating them, then creates the set with confirmation before each write.

Workflow

<Workflow - Router description="Dispatch a paa command to the right workflow." tools=[] triggers=["paa build", "paa help", "a request to build a personal agent, skill, and space from the user's own environment"]

1. [Decide] Choose one path.
   • "paa help" or a bare "paa" or "what can this do" go to <Workflow - Help>.
   • "paa build" or any build trigger go to <Workflow - Introspect>.
   • Ambiguous: ask the user which they want before proceeding. Validate: exactly one path chosen. If fails: ask one clarifying question. </Workflow - Router>

<Workflow - Introspect description="Read the person's environment, confirm identity, and gather only what introspection cannot supply." tools=[load_skill, recall_memories, kg_search, search_conversations, list_user_created_skills] triggers=["paa build"]

1. [Agent] Read README ## Pre-requisites and load the skills that provide these capabilities, matching by function if an exact name has changed: writing-style/voice cloning, agent creation, space creation and document upload, skill authoring, past-conversation search, and knowledge-graph search. Note which messaging or email connectors are available. Validate: each required skill loaded. If a required one fails: stop and link its install reference in <Resources>. If an optional messaging/email connector is missing: note reduced voice and role signal, continue.
2. [Agent] Anchor identity in a connected service (for example Slack whoami, or the signed-in email address). If none connected: proceed with memories and knowledge graph only.
3. [Agent] Read the environment in parallel: recall_memories, kg_search, search_conversations, list_user_created_skills, and the spaces and connector discovery tools. If a source returns nothing: note the gap and continue.
4. [Agent] Rank the person's most-used data sources and tools from what you found. Validate: at least one signal found. If none: tell the person and rely on their focus areas.
5. [Ask user] Ask for optional focus areas in one sentence.
6. [Ask user] Ask for response-style preferences using <Template - Response Style Prompt>.
7. [Agent] Present an evidence summary: inferred role, voice signals, top tools and data. Label anything unverified. Do not fabricate.
8. [Ask user] Confirm the summary before building. If fails: revise per feedback and re-present. </Workflow - Introspect>

<Workflow - Build Skill description="Build the personal voice-and-preference skill." tools=[start_task, save_engram, get_engram, save_skill, list_user_created_skills] triggers=["Called from Introspect after the person confirms the summary"]

1. [Agent] Start the voice engram as a background task (engram_builder), scanning the person's messages. Reuse this scan for role signal: top collaborators and recurring topics. Validate: the engram task started, or a no-message-source condition is recorded. If fails: skip the engram, note the voice profile is unavailable, and continue.
2. [Agent] Draft the personal skill: voice summary, stated preferences, and tool/data-source affinities from introspection. Keep it lean. No fabricated traits.
3. [Ask user] Show the draft and confirm before saving.
4. [Agent] Save the personal skill with save_skill, bundling any companion files in its scripts parameter. If it fails: report and stop.
5. [Agent] Refresh the skill registry with list_user_created_skills so the new skill is visible before the agent step. Validate: the new skill appears. If not: report and stop. </Workflow - Build Skill>

<Workflow - Build Space description="Create the space and preload it with the person's frequently-used data." tools=[create_space, write_quick_suite_file] triggers=["Called from Build Skill after the personal skill is saved"]

1. [Agent] Create the space (create_space), named for the person. If a matching space already exists: reuse it. Validate: a space exists to upload into. If fails: report the create error and stop before uploading.
2. [Ask user] Confirm which frequently-used documents to load, drawn from the ranking in Introspect.
3. [Agent] Upload the confirmed documents with write_quick_suite_file. If a file type is unsupported (see <Gotchas>): skip it and tell the person. Validate: each confirmed supported document uploaded. If an upload fails: report which and continue. </Workflow - Build Space>

<Workflow - Build Agent description="Create the lightweight, unscoped agent that names the personal skill and states the preferred response style." tools=[create_chat_agent, find_relevant_chat_agents] triggers=["Called from Build Space after the space is populated"]

1. [Agent] Check for an existing near-duplicate agent with find_relevant_chat_agents. If one clearly matches: surface it and offer to edit it instead, keeping "build new" open. If fails: proceed to build a new agent.
2. [Agent] Draft a lightweight agent: thin instructions that name the personal skill, state the person's preferred response style, and describe when to use the personal space. Leave Skills, Connectors, and Spaces unscoped (see <Gotchas>).
3. [Ask user] Show the agent draft and confirm before creating.
4. [Agent] Create the agent with create_chat_agent, passing no skill_ids, connector_arns, or space_arns so it stays unscoped. If it fails: report the error.
5. [Agent] Explain the scoping behavior from <Gotchas> so the person does not lock themselves in, and hand off. </Workflow - Build Agent>

<Workflow - Help description="Show the paa command menu." tools=[] triggers=["paa help", "paa"]

1. [Agent] Render <Template - Help Menu>, then wait for the person's choice. If fails: re-render from <Template - Help Menu>. </Workflow - Help>

<Template - Help Menu>

**Personal Agent Architect commands**

| Command | What it does |
| --- | --- |
| `paa help` | Show this menu. |
| `paa build` | Introspect your environment and build your personal skill, space, and agent. |

Say a command to start, or describe what you want in your own words.

</Template - Help Menu>

<Template - Response Style Prompt> Ask the person how they want their agent to respond, offering guiding examples so they are not starting from blank, and always leaving an "Other" option. Present as a single prompt:

How should your agent respond? Pick what fits, or choose Other to describe your own.

- Short, concise, factual prose.
- Simple choices, each with a recommendation and the reason for it.
- Bullet-point summaries with detail on request.
- Other (describe in your own words).

Capture the answer as the agent's stated response style, to be written into its instructions verbatim in intent. </Template - Response Style Prompt>