aos-harness 0.8.2 → 0.8.4

package/README.md

@@ -82,6 +82,43 @@ aos create profile my-review
 aos validate
 ```
 
+### Adapter Model Selection
+
+`aos run` resolves model settings in this order:
+
+1. adapter-scoped settings in `.aos/config.yaml` `adapter_defaults`
+2. legacy `.aos/adapter.yaml`
+3. `AOS_MODEL_ECONOMY` / `AOS_MODEL_STANDARD` / `AOS_MODEL_PREMIUM`
+4. adapter defaults
+
+Default behavior:
+
+- `pi` pins explicit tier models by default
+- `codex`, `claude-code`, and `gemini` let the vendor CLI choose its default model unless you set explicit tier models
+
+Example:
+
+```yaml
+api_version: aos/config/v2
+adapters:
+  enabled: [codex, pi]
+  default: codex
+adapter_defaults:
+  codex:
+    use_vendor_default_model: true
+  pi:
+    use_vendor_default_model: false
+    models:
+      economy: anthropic/claude-haiku-4-5
+      standard: anthropic/claude-sonnet-4-6
+      premium: anthropic/claude-opus-4-7
+```
+
+Claude Code note:
+
+- `aos init` now checks `claude auth status --json`.
+- If Claude Code is being forced through `ANTHROPIC_API_KEY`, the readiness scan will tell you. If sessions fail with `Invalid API key`, unset or refresh that key, or switch back to `claude login` auth.
+
 ## Exit Codes
 
 | Code | Meaning |

package/core/briefs/aos-education-series/brief.md

@@ -0,0 +1,114 @@
+# Brief: AOS Educational Content Series
+
+## Feature / Vision
+
+Create a public educational publishing series about AOS Harness, the Agentic Orchestration System behind my work. The series should introduce what AOS is, why it exists, how I use it, and how its major building blocks connect in practice: agents, profiles, domains, workflows, adapters, delegation, observability, and memory.
+
+This is not a product launch campaign. It is a discovery, education, and information-sharing series built around real work, real system design, and real lessons from building with AI. The tone should make readers feel that they are joining a practical journey: they are learning how modern AI systems can be structured, how orchestration improves outcomes, and how they can try small pieces themselves.
+
+The first article should give a clear overview of what AOS Harness is and set the expectation that new posts will continue every week, with the option to publish twice a week. Every post should leave the reader with:
+
+- one clear idea they now understand better
+- one practical takeaway or tiny action they can try
+- one reason to come back for the next post
+
+The publishing goal is to grow an audience around thoughtful, motivating, technically grounded writing on AI orchestration, while also documenting my own expertise and evolution as a builder using AOS Harness.
+
+## Context
+
+- AOS Harness is described in this repository as an "Agentic Orchestration System" that assembles specialized AI agents into deliberation and execution teams.
+- The current repo supports two major orchestration patterns:
+  - Deliberation: multi-agent debate that produces a structured memo
+  - Execution: orchestrated workflow that produces an execution package or working implementation output
+- The repo currently includes:
+  - 15 agent personas
+  - 8 orchestration profiles
+  - 5 domain packs
+  - 5 skill definitions
+  - adapters for Codex, Claude Code, Gemini, and Pi
+- Important system ideas already documented in the repo include:
+  - cognitive diversity through agent roles and biases
+  - tension pairs and speaks-last structural design
+  - profiles as reusable agent assemblies
+  - domains as append-only knowledge overlays
+  - domain enforcement as real adapter-layer file and tool boundaries
+  - workflow-driven execution
+  - hierarchical delegation
+  - transcript events, replay, and event summarization
+  - persistent expertise and MemPalace-backed memory
+  - session resumption
+- This content series should reflect what is actually in the repo today, not generic AI commentary.
+- Primary channels are LinkedIn posts and a newsletter-style written format. The same core ideas should be reusable across both.
+- The public-facing narrative should treat the project name as **AOS Harness** and the system concept as **AOS: Agentic Orchestration System**.
+
+## Constraints
+
+- Keep the writing grounded in the real architecture and terminology of this repository.
+- Avoid inflated "AI will change everything" language. The writing should be motivating, but specific.
+- Each post should focus on one central concept only.
+- Each post should connect the concept to an outcome readers care about: clarity, reliability, safety, speed, structure, or learning.
+- Each post should include a small actionable element such as:
+  - install this
+  - run this
+  - read this output
+  - compare these two profiles
+  - create this first config
+- Each post should end with a soft bridge to the next article so the series feels continuous.
+- The series should work for mixed audiences:
+  - curious builders new to AI orchestration
+  - developers already using AI tools but not yet orchestrating teams of agents
+  - technical leaders evaluating how to structure AI work
+- The content should ladder from simple to advanced:
+  - what AOS is
+  - how the parts fit together
+  - how to run it
+  - how to customize it
+  - how to learn from it
+  - how to build with it
+- Prefer a 12-week season with 2 posts per week so there is enough room to cover the system without rushing.
+- Keep the public writing educational first, lightly invitational second, and promotional third.
+
+## Success Criteria
+
+- Produce a clear content strategy for a 12-week educational series about AOS Harness.
+- Define the audience, positioning, publishing tone, and recurring structure for each post.
+- Create a concrete topic map that covers the major system components in a logical order.
+- Ensure the series includes dedicated coverage of:
+  - agents
+  - profiles
+  - domains
+  - workflows
+  - adapters
+  - hierarchical delegation
+  - domain enforcement
+  - transcripts and observability
+  - session replay and resumption
+  - memory and MemPalace
+  - creating custom components in the harness
+- For each planned post, define:
+  - working title
+  - core lesson
+  - reader takeaway
+  - small hands-on prompt or action
+  - teaser for the next post
+- Make the first post a general overview of AOS Harness and the learning journey readers are being invited into.
+- Make the full series feel cumulative so each post builds understanding and momentum for the next one.
+
+## Requested Deliverables
+
+Generate a planning package that includes:
+
+- a series positioning statement
+- target audience segments
+- tone and voice guidance
+- a 12-week editorial calendar
+- 24 post concepts with short descriptions
+- a reusable post template for LinkedIn and newsletter formats
+- suggestions for recurring calls to action
+- suggestions for how to turn repo concepts into motivating educational examples
+
+## Seed Narrative
+
+This series should feel like an open workshop in public:
+
+"I am building and refining AOS Harness in the open. Each article explains one part of the system, what problem it solves, how it connects to the rest of the architecture, and how you can start experimenting with the same ideas yourself. If you follow the series from the beginning, you should gradually move from curiosity about AI to a practical understanding of structured AI orchestration."

package/core/briefs/aos-education-series/editorial-plan.md

@@ -0,0 +1,285 @@
+# AOS Educational Series Editorial Plan
+
+## Purpose
+
+This plan turns the AOS educational brief into a concrete publishing sequence for LinkedIn plus a longer-form newsletter or blog. The structure is designed to make the series cumulative, practical, and easy to convert into prompts later.
+
+## Recommended Positioning
+
+**Series promise:** Learn AI orchestration by following a real system in the open.
+
+**Core message:** AOS Harness is not "more AI for the sake of AI." It is a way to structure intelligence so different agent roles, constraints, workflows, and memory systems work together deliberately.
+
+**What makes the series worth following:**
+
+- It is grounded in a real repo and real architecture.
+- It teaches concepts in sequence instead of dropping isolated tips.
+- It gives readers small actions so they can build confidence as they go.
+- It shows AI as a system design discipline, not only as prompting.
+
+## Audience
+
+1. Builders who already use AI tools but want more reliable and structured results.
+2. Engineers who want to understand multi-agent architecture without starting from theory alone.
+3. Technical leaders exploring how AI can support planning, review, and execution work.
+4. Curious learners who want a guided, motivating path into agentic systems.
+
+## Publishing Cadence
+
+- Recommended cadence: 2 posts per week
+- Format:
+  - Post A: concept, architecture, or philosophy
+  - Post B: practical use, walkthrough, or system connection
+- Primary channel: LinkedIn
+- Secondary channel: newsletter or blog archive
+
+## Recurring Post Structure
+
+Use this structure for nearly every post:
+
+1. Hook
+2. One concept explained clearly
+3. Why it matters in AOS Harness
+4. One concrete example from the repo or workflow
+5. One takeaway
+6. One tiny action for the reader
+7. One teaser for the next post
+
+## Tone Guide
+
+- Clear, practical, confident
+- Educational without sounding academic
+- Motivating without sounding inflated
+- Open about lessons, tradeoffs, and design choices
+- More "here is how this works" than "look how impressive this is"
+
+## Calls To Action
+
+Rotate soft calls to action instead of repeating the same one.
+
+- Follow the series for the next building block.
+- Try the command and compare the output.
+- Read the next post before you customize your own setup.
+- Fork the idea, even if you do not use this exact repo.
+- Think about where this pattern applies in your own workflow.
+
+## Season 1 Outline
+
+### Week 1
+
+**Post 1A**
+- Title: What AOS Harness Is and Why I Am Writing About It in Public
+- Core lesson: AOS Harness is an Agentic Orchestration System for structured deliberation and execution, not just a wrapper around a model.
+- Reader takeaway: AI becomes more useful when roles, constraints, and outputs are designed intentionally.
+- Tiny action: Read the repo README and identify the two orchestration modes: deliberation and execution.
+- Next teaser: Next I will explain why AOS uses multiple agents instead of one smart assistant.
+
+**Post 1B**
+- Title: Why One AI Agent Is Not Enough for Serious Work
+- Core lesson: AOS creates cognitive diversity through specialist agents with distinct biases, risk tolerances, and reasoning styles.
+- Reader takeaway: Better outcomes often come from structured disagreement, not a single polished answer.
+- Tiny action: Review the agent roster and pick the three roles you would want in a decision meeting.
+- Next teaser: Next I will break down how agents are assembled into profiles.
+
+### Week 2
+
+**Post 2A**
+- Title: Meet the AOS Agents: Bias by Design
+- Core lesson: Agents such as Catalyst, Sentinel, Architect, and Provocateur are designed to create productive tension.
+- Reader takeaway: Multi-agent quality depends on meaningful role design, not simply multiplying model calls.
+- Tiny action: Compare Catalyst and Sentinel and write one sentence on why both are needed.
+- Next teaser: Next I will show how these agents become repeatable systems through profiles.
+
+**Post 2B**
+- Title: Profiles: The Real Unit of Reuse in AOS
+- Core lesson: Profiles define who participates, how they interact, and what kind of output gets produced.
+- Reader takeaway: Reusability in orchestration comes from repeatable assemblies, not ad hoc prompting.
+- Tiny action: Compare `strategic-council` and `cto-execution` and list what changes between them.
+- Next teaser: Next I will show how the same system shifts from debate into execution.
+
+### Week 3
+
+**Post 3A**
+- Title: Deliberation vs Execution: Two Different Ways to Use AI Teams
+- Core lesson: AOS supports both debate-oriented sessions and workflow-driven execution packages.
+- Reader takeaway: The right orchestration pattern depends on whether you need judgment, production, or both.
+- Tiny action: Read the output expectations for a memo versus an execution package.
+- Next teaser: Next I will show why the brief matters more than most people think.
+
+**Post 3B**
+- Title: A Better Brief Produces Better AI Work
+- Core lesson: AOS uses structured briefs so sessions begin with clear intent, context, constraints, and success criteria.
+- Reader takeaway: The brief is not paperwork; it is the contract that shapes the run.
+- Tiny action: Draft a four-section brief for a problem you care about.
+- Next teaser: Next I will explain how domains make the same agents smarter in different industries.
+
+### Week 4
+
+**Post 4A**
+- Title: Domains: How AOS Learns the Language of an Industry
+- Core lesson: Domains are append-only overlays that inject industry-specific language, heuristics, and context into the same base system.
+- Reader takeaway: Good orchestration separates general reasoning from domain-specific context.
+- Tiny action: Review one existing domain pack and note what it changes.
+- Next teaser: Next I will show that domains are not only knowledge overlays, they are also safety boundaries.
+
+**Post 4B**
+- Title: Domain Enforcement: Real Boundaries, Not Prompt Theater
+- Core lesson: AOS enforces file and tool permissions at the adapter layer, not only in text instructions.
+- Reader takeaway: Reliable AI systems need actual boundaries, not just polite reminders.
+- Tiny action: Read the domain enforcement docs and sketch the minimum file access a worker should have in your own repo.
+- Next teaser: Next I will move from boundaries to capabilities: skills and tools.
+
+### Week 5
+
+**Post 5A**
+- Title: Skills: What Happens When Agents Need More Than Conversation
+- Core lesson: Skills let agents invoke specialized capabilities such as review, decomposition, or memory tooling in a structured way.
+- Reader takeaway: Orchestration gets stronger when capabilities are explicit and scoped.
+- Tiny action: Inspect the existing skills and decide which one you would want first in your own workflow.
+- Next teaser: Next I will explain how all of this stays portable across different AI runtimes.
+
+**Post 5B**
+- Title: Adapters: Why AOS Works Across Codex, Claude, Gemini, and Pi
+- Core lesson: AOS separates orchestration logic from runtime-specific integration through a 4-layer adapter contract.
+- Reader takeaway: Portability comes from clear boundaries between system design and platform execution.
+- Tiny action: Identify which adapter matches the CLI you already use.
+- Next teaser: Next I will connect adapters to workflows and show how the system turns intent into deliverables.
+
+### Week 6
+
+**Post 6A**
+- Title: Workflows: Turning AI Collaboration into Repeatable Delivery
+- Core lesson: Workflows define ordered steps, review gates, and artifact handoffs so complex work can be repeated consistently.
+- Reader takeaway: The jump from "chatting with AI" to "shipping with AI" happens through workflow design.
+- Tiny action: Read the `cto-execution` workflow summary and identify its review gates.
+- Next teaser: Next I will open up the execution package and show what useful output actually looks like.
+
+**Post 6B**
+- Title: Inside the CTO Execution Package
+- Core lesson: AOS can generate requirements, architecture, planning, risk review, and implementation checklists in one orchestrated run.
+- Reader takeaway: Good AI output is structured, reviewable, and ready for handoff.
+- Tiny action: Review the sample brief and imagine how you would reuse the output in your own team.
+- Next teaser: Next I will move from planning to implementation with dev execution.
+
+### Week 7
+
+**Post 7A**
+- Title: Dev Execution: From Brief to Working Code
+- Core lesson: Dev Execution combines planning, worker coordination, review, and test verification in one session.
+- Reader takeaway: Orchestrated AI can move from thinking to doing if each phase is explicit.
+- Tiny action: Read the dev-execution docs and note the four approval gates.
+- Next teaser: Next I will show how the engineering lead and worker model actually works under the hood.
+
+**Post 7B**
+- Title: Hierarchical Delegation: How One Agent Becomes a Team Lead
+- Core lesson: AOS supports lead agents that spawn scoped child agents under depth and permission limits.
+- Reader takeaway: Delegation is powerful when authority, scope, and communication paths are controlled.
+- Tiny action: Sketch a three-role worker tree for a feature in your own codebase.
+- Next teaser: Next I will show how to observe all this activity instead of treating AI work as a black box.
+
+### Week 8
+
+**Post 8A**
+- Title: Observability for AI Work: Why Transcript Events Matter
+- Core lesson: AOS emits structured transcript events so sessions can be reviewed, replayed, and understood.
+- Reader takeaway: If AI work cannot be inspected, it cannot be trusted or improved systematically.
+- Tiny action: List the three session events you would most want to see in a dashboard.
+- Next teaser: Next I will show how replay and summarized events turn runs into learning assets.
+
+**Post 8B**
+- Title: Replay, Summaries, and Learning from Past Sessions
+- Core lesson: AOS supports replay and event summarization so sessions can be revisited without rereading raw logs.
+- Reader takeaway: AI systems improve faster when runs become inspectable learning records.
+- Tiny action: Read the event summarization docs and note which events are most meaningful to humans.
+- Next teaser: Next I will move from observability into memory.
+
+### Week 9
+
+**Post 9A**
+- Title: Memory in AOS: Why Context Should Survive the Session
+- Core lesson: AOS supports pluggable memory so useful insights can carry across runs instead of resetting every time.
+- Reader takeaway: Persistent AI systems need selective memory, not endless transcript stuffing.
+- Tiny action: Read `.aos/memory.yaml` guidance and identify what you would want remembered from your own sessions.
+- Next teaser: Next I will explain why MemPalace is recommended and how it fits into the system.
+
+**Post 9B**
+- Title: MemPalace and Institutional Memory for Agentic Systems
+- Core lesson: MemPalace provides high-fidelity semantic recall while the orchestrator gates what gets remembered and recalled.
+- Reader takeaway: Memory quality depends on curation and retrieval design, not only storage.
+- Tiny action: Map the MemPalace concepts of wing, room, hall, and drawer to your own work.
+- Next teaser: Next I will show how long-running work resumes without losing the thread.
+
+### Week 10
+
+**Post 10A**
+- Title: Session Resumption: Continuing Work Without Starting Over
+- Core lesson: AOS checkpoints sessions and rehydrates agents with filtered transcript tails and expertise snapshots.
+- Reader takeaway: Long AI workflows need pause-and-resume mechanics just like human work does.
+- Tiny action: Think about one AI workflow in your life that breaks because it cannot resume cleanly.
+- Next teaser: Next I will connect memory and resumption into a bigger idea: durable AI collaboration.
+
+**Post 10B**
+- Title: Durable AI Collaboration Is More Than a Better Prompt
+- Core lesson: The combination of briefs, workflows, memory, replay, and resumption creates continuity.
+- Reader takeaway: Real AI systems need operating structure, not isolated tricks.
+- Tiny action: Write down which layer you are missing today: role design, constraints, memory, or observability.
+- Next teaser: Next I will show how to start customizing AOS for your own use case.
+
+### Week 11
+
+**Post 11A**
+- Title: Creating Your Own Agents
+- Core lesson: AOS agents are defined through schema, persona, heuristics, evidence standards, tensions, and prompts.
+- Reader takeaway: Strong agent design is a product of sharp role boundaries and useful disagreement.
+- Tiny action: Draft one custom agent with a name, bias, risk tolerance, and red line.
+- Next teaser: Next I will show how to turn agents into profiles and domains that fit your world.
+
+**Post 11B**
+- Title: Creating Your Own Profiles and Domains
+- Core lesson: Profiles and domains let you turn one-off experiments into repeatable systems for your context.
+- Reader takeaway: The real leverage comes when your orchestration becomes reusable.
+- Tiny action: Choose one industry or team context and outline the first domain overlay you would need.
+- Next teaser: Next I will close the season by looking at community, extensibility, and where this can go next.
+
+### Week 12
+
+**Post 12A**
+- Title: Extensibility: Registry, Community, and the Shape of an AOS Ecosystem
+- Core lesson: AOS is structured so agents, profiles, and domains can be shared and validated consistently.
+- Reader takeaway: A system becomes an ecosystem when its building blocks are portable and inspectable.
+- Tiny action: Review the registry docs and imagine the first community contribution you would make.
+- Next teaser: Next I will wrap the season with the biggest lessons from building and teaching AOS in public.
+
+**Post 12B**
+- Title: What This Series Taught Me About Building with AI
+- Core lesson: The deeper lesson of AOS is that AI gets more useful when you treat it as architecture, not magic.
+- Reader takeaway: Readers should leave the season with a mental model for structured AI work.
+- Tiny action: Pick one idea from the season and implement it in your own process this week.
+- Next teaser: Season 2 can move into advanced build diaries, case studies, and domain-specific orchestration.
+
+## Reusable Prompt Inputs
+
+When you later turn this plan into prompt inputs, keep these fields for every post:
+
+- audience
+- channel
+- post title
+- core lesson
+- problem it solves
+- repo concept to reference
+- practical example
+- takeaway
+- tiny action
+- teaser for next post
+- tone notes
+
+## Recommendation
+
+Start with Season 1 exactly as a guided on-ramp:
+
+- Weeks 1 to 3: orient the audience
+- Weeks 4 to 7: explain the machinery
+- Weeks 8 to 10: explain reliability and continuity
+- Weeks 11 to 12: show customization and long-term vision
+
+That sequencing gives readers early clarity, mid-series excitement, and a credible reason to keep following the work.

package/core/briefs/aos-education-series/prompt-pack/00-strategic-council-run-brief.md

@@ -0,0 +1,57 @@
+# Brief: AOS Educational Series Strategy
+
+## Situation
+
+I am building a public educational content series around **AOS Harness**, the Agentic Orchestration System represented in this repository. The goal is to publish consistently, likely weekly or twice weekly, across LinkedIn and a newsletter or blog format.
+
+The series is meant to document and teach the real architecture and working ideas behind AOS Harness: agents, profiles, domains, workflows, adapters, domain enforcement, hierarchical delegation, transcripts, replay, session resumption, and memory with MemPalace. I want the series to reflect how I actually build and think with AI, not generic commentary about AI trends.
+
+I already have:
+
+- an execution-style planning brief at `core/briefs/aos-education-series/brief.md`
+- an editorial outline at `core/briefs/aos-education-series/editorial-plan.md`
+- a prompt pack for drafting, adaptation, and NotebookLM support under `core/briefs/aos-education-series/prompt-pack/`
+
+What I need now is strategic guidance on how to shape the series so it becomes:
+
+- educational and cumulative
+- motivating and exciting
+- grounded in the actual repo
+- useful to new and intermediate builders
+- strong enough to keep readers returning over time
+
+## Stakes
+
+**Upside if this is designed well**
+
+- The series becomes a clear public learning path into AI orchestration.
+- Readers understand AOS Harness as a real system, not just a project name.
+- The content establishes credibility around my expertise in structuring and using AI systems.
+- The posts create a compounding audience that can later engage with deeper tutorials, case studies, and adoption stories.
+- The writing becomes a reusable knowledge asset for AOS, NotebookLM, and future product education.
+
+**Downside if this is designed poorly**
+
+- The series becomes too abstract, too technical too early, or too repetitive.
+- Readers fail to understand how the AOS components connect together.
+- The writing sounds like generic AI thought leadership instead of a grounded system walkthrough.
+- I lose momentum because the series lacks a clear arc and practical production workflow.
+- Valuable architecture in the repo remains invisible to the audience it could help.
+
+## Constraints
+
+- The content must stay grounded in the real AOS Harness repo and docs.
+- The tone should be educational before promotional.
+- Each post should teach one central idea only.
+- The sequence must build from beginner-friendly orientation into more advanced architecture and customization topics.
+- Every post should include a practical takeaway and a small action or reflection.
+- The series should work across LinkedIn and a longer-form written medium.
+- The public narrative should use **AOS Harness** as the project name and **AOS: Agentic Orchestration System** as the system concept.
+
+## Key Question
+
+How should I structure and position this AOS Harness educational series so it becomes a compelling long-running public journey that teaches AI orchestration clearly, builds reader momentum week by week, and turns the real architecture of the repo into useful, motivating content?
+
+## Context Files
+
+**Context files:** core/briefs/aos-education-series/brief.md, core/briefs/aos-education-series/editorial-plan.md, core/briefs/aos-education-series/prompt-pack/01-aos-series-strategy-analysis.md, README.md, docs/getting-started/README.md, docs/domain-enforcement/README.md, docs/hierarchical-delegation/README.md, docs/persistent-expertise/README.md, docs/session-resumption/README.md, docs/dev-execution/README.md

package/core/briefs/aos-education-series/prompt-pack/01-aos-series-strategy-analysis.md

@@ -0,0 +1,51 @@
+# Prompt: AOS Series Strategy Analysis
+
+Use this prompt with an AOS deliberation profile such as `strategic-council`.
+
+## Goal
+
+Analyze the AOS educational brief as a content strategy problem and produce a stronger publishing strategy, sharper audience positioning, clearer sequencing, and practical guidance for turning the series into a sustained public learning journey.
+
+## Prompt
+
+```text
+You are analyzing an educational publishing strategy for AOS Harness.
+
+Use the attached brief and editorial plan as your primary context.
+
+Your job is to evaluate the series as if it were a product and learning system:
+
+1. Is the positioning clear and distinctive?
+2. Is the target audience segmented correctly?
+3. Does the sequence move from beginner-friendly topics to higher-leverage ideas in the right order?
+4. Which topics are strongest for early audience growth?
+5. Which topics risk being too abstract, too advanced, or too repetitive?
+6. Where should practical examples, commands, repo walkthroughs, or mini-challenges be inserted?
+7. What narrative arcs will keep readers returning week after week?
+8. What should be simplified, combined, split, or moved?
+
+Produce the output in this structure:
+
+- Executive assessment
+- Audience and positioning improvements
+- Sequence improvements
+- Early-post optimization recommendations
+- Risks and blind spots
+- Recommended recurring content mechanics
+- A revised season architecture
+- 5 high-leverage experiments for the first month
+
+Important constraints:
+
+- Ground your recommendations in the real AOS Harness architecture and docs
+- Do not turn the series into generic AI thought leadership
+- Optimize for clarity, learning progression, and reader retention
+- Keep the advice practical enough to implement immediately
+```
+
+## Best Inputs
+
+- [../brief.md](../brief.md)
+- [../editorial-plan.md](../editorial-plan.md)
+- [README.md](/Users/jkolade/sireskay/github/aos-framework/README.md)
+- [docs/white-paper/aos-harness-features.md](/Users/jkolade/sireskay/github/aos-framework/docs/white-paper/aos-harness-features.md)

package/core/briefs/aos-education-series/prompt-pack/02-aos-brief-validation.md

@@ -0,0 +1,37 @@
+# Prompt: AOS Brief Validation
+
+Use this prompt with AOS when you want the harness to critique and strengthen the brief itself before you generate content.
+
+## Prompt
+
+```text
+Review this AOS educational-series brief as if it were going to drive an important multi-week execution effort.
+
+Evaluate it on:
+
+- clarity of goal
+- quality of context
+- usefulness of constraints
+- specificity of success criteria
+- missing assumptions
+- hidden ambiguities
+- execution risk
+- narrative strength
+
+Then do three things:
+
+1. List the weaknesses or gaps in priority order
+2. Rewrite the brief so it is more precise and more usable by AOS
+3. Suggest optional context files or repo artifacts that should be attached when running the brief
+
+Important:
+
+- Preserve the intent of the original brief
+- Keep the writing grounded in the AOS Harness repo
+- Improve specificity without making the brief bloated
+- Call out any wording that could confuse agents or produce vague outputs
+```
+
+## Output Expectation
+
+The ideal result is a cleaner, sharper brief that can be used for repeated planning runs over time.

package/core/briefs/aos-education-series/prompt-pack/03-season-architecture-prompt.md

@@ -0,0 +1,39 @@
+# Prompt: Season Architecture
+
+Use this prompt when you want a stronger high-level season structure before drafting individual posts.
+
+## Prompt
+
+```text
+Design Season 1 of the AOS educational publishing series as a learning architecture.
+
+Use the attached brief and editorial plan.
+
+Your task is to improve the season structure so it behaves like a guided curriculum and a content engine at the same time.
+
+Define:
+
+- the season theme
+- the 4 major phases of the season
+- the learning objective of each phase
+- the emotional objective of each phase
+- the right ratio of concept posts vs practical posts
+- the best point to introduce harder topics like delegation, memory, and replay
+- the ideal weekly cadence and rhythm
+- where to place "checkpoint" recap posts or summary posts if needed
+
+Then provide:
+
+- a refined 12-week map
+- reasons for the ordering
+- top 6 posts that should receive the most writing energy
+- 3 optional bonus posts for schedule flexibility
+
+Constraints:
+
+- Avoid front-loading too much complexity
+- Make the season feel cumulative
+- Ensure the first 3 weeks are welcoming to new readers
+- Ensure the middle weeks deepen technical trust
+- Ensure the last weeks move readers toward customization and adoption
+```