intent-framed-agent

# Intent Framed Agent ## Install ```bash npx skills add pskoett/pskoett-ai-skills ``` ```bash npx skills add pskoett/pskoett-ai-skills/skills/intent-framed-agent ``` ## Purpose This skill turns implicit intent into an explicit, trackable artifact at the moment execution starts. It creates a lightweight intent contract, watches for scope drift while work is in progress, and closes each intent with a short resolution record. ## Scope (Important) Use this skill for coding tasks only. It is designed for implementation work that changes executable code. Do not use it for general-agent activities such as: - broad research - planning-only conversations - documentation-only work - operational/admin tasks with no coding implementation For trivial edits (for example, simple renames or typo fixes), skip the full intent frame. ## Trigger Activate at the planning-to-execution transition for non-trivial coding work. Common cues: - User says: "go ahead", "implement this", "let's start building" - Agent is about to move from discussion into code changes ## Workflow ### Phase 1: Intent Capture At execution start, emit: ```markdown ## Intent Frame #N **Outcome:** [One sentence. What does done look like?] **Approach:** [How we will implement it. Key decisions.] **Constraints:** [Out-of-scope boundaries.] **Success criteria:** [How we verify completion.] **Estimated complexity:** [Small / Medium / Large] ``` Rules: - Keep each field to 1-2 sentences. - Ask for confirmation before coding: - `Does this capture what we are doing? Anything to adjust before I start?` - Do not proceed until the user confirms or adjusts. ### Phase 2: Intent Monitor During execution, monitor for drift at natural boundaries: - before touching a new area/file - before starting a new logical work unit - when current action feels tangential Drift examples: - work outside stated scope - approach changes with no explicit pivot - new features/refactors outside constraints - solving a different problem than the stated outcome When detected, emit: ```markdown ## Intent Check #N This looks like it may be moving outside the stated intent. **Stated outcome:** [From active frame] **Current action:** [What is happening] **Question:** Is this a deliberate pivot or accidental scope creep? ``` If pivot is intentional, update the active intent frame and continue. If not, return to the original scope. ### Phase 3: Intent Resolution When work under the active intent ends, emit: ```markdown ## Intent Resolution #N **Outcome:** [Fulfilled / Partially fulfilled / Pivoted / Abandoned] **What was delivered:** [Brief actual output] **Pivots:** [Any acknowledged changes, or None] **Open items:** [Remaining in-scope items, or None] ``` Resolution is preferred but optional if the session ends abruptly. ## Multi-Intent Sessions One session can contain multiple intent frames. Rules: 1. Resolve current intent before opening the next. 2. If user changes direction mid-task, resolve current intent as `Abandoned` or `Pivoted`, then open a new frame. 3. Drift checks always target the currently active frame. 4. Number frames sequentially within the session (`#1`, `#2`, ...). 5. Constraints do not carry forward unless explicitly restated. ## Entire CLI Integration Entire CLI: https://github.com/entireio/cli When tool access is available, detect Entire at activation: ```bash entire status 2>/dev/null ``` - If it succeeds, mention that intent records will be captured in the session transcript on the checkpoint branch. This enables `learning-aggregator --deep` to later mine intent frames and drift events for cross-session scope-drift patterns. - If unavailable/failing, continue silently. Do not block execution and do not nag about installation. Copilot/chat fallback: - If command execution is unavailable, skip detection and continue with the same intent workflow in chat output. ### How intent frames become learning signals Each Intent Frame and Intent Check you emit is captured verbatim in Entire's session transcript. At cadence, `learning-aggregator --deep` reads those transcripts and extracts: - Frames that were resolved as `Abandoned` or `Pivoted` → potential planning gaps - Drift signals that repeatedly fire in similar contexts → potential scope definition issues - Constraint violations detected by drift checks → patterns for promotion to project instruction files You do not need to do anything special for this — the intent blocks are structured (`## Intent Frame #N`, `## Intent Check`, `## Intent Resolution`), which makes them parseable from the transcript. ## Guardrails - Keep it lightweight; avoid long prose. - Do not over-trigger on trivial tasks. - Do not interrupt on every small step. - Treat acknowledged pivots as valid. - Preserve exact structured block headers/fields for parseability. ## Interoperability with Other Skills Use this skill as the front-door alignment layer for non-trivial coding work: 1. `plan-interview` (optional, for requirement shaping) 2. `intent-framed-agent` (execution contract + scope drift monitoring) 3. `context-surfing` (context quality monitoring — runs concurrently with intent-framed-agent during execution) 4. `simplify-and-harden` (post-completion quality/security pass) 5. `self-improvement` (capture recurring patterns and promote durable rules) ### Relationship with context-surfing Both skills are live during execution. They monitor different failure modes: - **intent-framed-agent** monitors *scope* drift — is the agent doing the right thing? It fires structured Intent Checks when work moves outside the stated outcome. - **context-surfing** monitors *context quality* drift — is the agent still capable of doing it well? It fires when the agent's own coherence degrades (hallucination, contradiction, hedging). They are complementary, not redundant. An agent can be perfectly on-scope while its context quality degrades. Conversely, scope drift can happen with perfect context quality. Intent Checks continue firing alongside context-surfing's wave monitoring. **Precedence rule:** If both skills fire simultaneously (an Intent Check and a context-surfing drift exit at the same time), the drift exit takes precedence. Degraded context makes scope checks unreliable — resolve the context issue first, then resume scope monitoring in the next session. ### What this skill produces - **Intent frame artifact** — consumed by context-surfing as part of the wave anchor and copied verbatim into handoff files on drift exit. - **Intent resolution** — signals task completion, which triggers simplify-and-harden. - **Drift observations** — scope drift patterns can be logged to self-improvement as learnings if they recur.