@thebackstoryis/engineering-with-ai 0.3.0 → 0.3.1-beta.0

package/Docs/README.md

@@ -30,6 +30,8 @@ If you have a persona licence, [set it up before the analysis](operations/premiu
 
 If you're contributing without an engineering background, use the [non-technical team guide](adoption/non-technical-team-guide.md). For examples of the wider workflow, see [worked examples](examples/worked-examples.md).
 
+To try the beta communication guidance, read [concise answers and guided decisions](context-management-and-token-efficiency.md#concise-answers-and-guided-decisions), including examples and installation instructions.
+
 ## Make the dashboard work for you
 
 [Choose which views you need](operations/dashboard-configuration.md). Portfolio, Team Hub, policy tools and the other advanced views are optional and start hidden. Showing a view doesn't configure the service behind it; hiding one doesn't remove checks your project requires.

package/Docs/context-management-and-token-efficiency.md

@@ -6,6 +6,48 @@ You normally don't prepare context manually: the relevant EWAI skill does that f
 
 Context preparation doesn't approve Build or Manual QA, accept risk, certify quality, deploy or release.
 
+## Concise answers and guided decisions
+
+**Availability:** This guidance is included in `0.3.1-beta.0`. Follow [beta installation](operations/installation-updating-and-entitlements.md#try-the-beta-channel), then initialise the project or run its normal EWAI check-in to refresh the managed instructions in `AGENTS.md` and `CLAUDE.md`. Start a fresh host conversation after the refresh. Project-authored guidance outside the managed block is preserved. npm `0.3.0` does not include these new instructions. Tool-result compaction remains planned, and no incremental token or cost saving has been measured for this update.
+
+### Get a useful short answer
+
+Describe the result you need, for example:
+
+> “Give me the result and next action concisely. Keep the evidence, exact commands, important risks and anything you couldn't verify.”
+
+The guidance prioritises correctness and usefulness, then brevity. Expect the result or recommendation first, with less repetition and routine narration. Required status, warnings and approval steps still appear. A short answer should retain prerequisites, meaningful action order, failures and uncertainty; it should not replace working instructions with shorthand.
+
+When you need more detail, ask for it:
+
+> “Expand the migration steps, including prerequisites, verification and recovery.”
+
+Detailed requests still need complete answers. If a concise answer leaves you unable to act safely or understand the evidence, ask for the missing detail before acting.
+
+### Make an informed decision
+
+A decision request should explain the action, consequences, material options and tradeoffs, then give a recommendation with its reason. A suggested response can help you express your choice; it does not record approval on your behalf.
+
+You can ask:
+
+> “Explain what I need to decide, recommend an option with its reason, and suggest a reply. Include what happens next and any uncertainty.”
+
+When the evidence cannot support a choice, expect a recommendation for the next evidence-gathering step. Build approval, Manual QA and release decisions still need their own explicit authority; see [who approves what](human-approval-and-assurance-guide.md).
+
+### Refine an unclear request
+
+The guidance leads with a recommended interpretation and explains assumptions that affect the outcome. It asks one focused question when missing information materially changes the scope or next action, with guidance and a recommended response.
+
+For example, if you say “Make onboarding simpler”, an illustrative response is:
+
+> “I recommend reviewing the existing onboarding journey first to identify where people get stuck. I'm assuming you want the journey assessed before changing the implementation. Should we start with that review? Suggested response: ‘Yes, review the journey first and recommend changes.’”
+
+Correct the interpretation when it misses your intent. Work already authorised and independent of your answer can continue; a proposed interpretation or suggested reply does not expand that authority.
+
+### Understand savings claims
+
+Shorter replies aim to reduce output tokens. The context preparation described below addresses input tokens. Neither a shorter example nor the packaged context benchmark establishes whole-session cost savings. Assess equivalent work using actual provider usage where available, including retries and clarification rounds, alongside correctness and how well the answer supports your decision. Unknown usage remains unknown.
+
 ## Inspect the evidence sent to the model
 
 Open **Configuration**, enable **AI context diagnostics** and save, then open that view in the sidebar. See [dashboard configuration](operations/dashboard-configuration.md) if you need help finding it.

package/Docs/guide-catalogue.md

@@ -20,6 +20,7 @@ Choose the section that matches your job. The optional team tools aren't prerequ
 - [Facilitate project Discovery](guided-discovery-facilitator-guide.md)
 - [Create or revise an intent in Intent Studio](guided-intent-workspace-guide.md)
 - [Choose work with the Companion](context-aware-delivery-companion-user-guide.md)
+- [Get concise answers and useful decision guidance (beta)](context-management-and-token-efficiency.md#concise-answers-and-guided-decisions)
 - [Delegate an exact pool of intents with guarded autonomy](autonomous-intent-delivery.md)
 - [Contribute information to work in progress](guided-phase-evidence-drafting-guide.md)
 - [Review evidence from meeting notes or transcripts](meeting-evidence-user-guide.md)

package/Docs/operations/installation-updating-and-entitlements.md

@@ -46,6 +46,23 @@ npx --yes @thebackstoryis/engineering-with-ai@latest
 
 This asks npm to obtain and run the package. It doesn't create a standing global installation.
 
+## Try the beta channel
+
+The beta channel is an opt-in prerelease. Version `0.3.1-beta.0` adds [concise answers and guided decisions](../context-management-and-token-efficiency.md#concise-answers-and-guided-decisions); production remains `0.3.0`.
+
+For one project:
+
+```bash
+npm install --save-dev @thebackstoryis/engineering-with-ai@beta
+npx ewai
+```
+
+To pin this specific beta instead of following the beta channel, replace `@beta` with `@0.3.1-beta.0`. For a global beta installation, use `npm install --global @thebackstoryis/engineering-with-ai@beta`, then start EWAI in your project folder.
+
+Initialisation or normal check-in refreshes the EWAI-managed block in `AGENTS.md` and `CLAUDE.md`. Guidance outside that block is preserved. In an existing project, you can refresh explicitly with `npx ewai checkin --project . --json` for a project dependency, or `ewai checkin --project . --json` for a global installation. Start a fresh host conversation after refreshing so it reads the new instructions. Review changes to your project's package, lockfile and instruction files before committing them.
+
+Beta check-in offers updates from the beta channel. To return to production deliberately, install `@latest` using the same project-local or global scope, then run that version's check-in and start a fresh conversation. Review the instruction changes and use [dashboard recovery](troubleshooting-and-recovery.md#dashboard-will-not-start) if an older runtime is still running. Returning to production does not undo work already performed in your application.
+
 ## Start your project
 
 Open your project folder in the host and start EWAI. Agree where its SPECS folder should live before initialising it. For existing code, EWAI offers Archaeology to reconstruct missing project knowledge; you can accept or decline it.

package/README.md

@@ -2,6 +2,21 @@
 
 Engineering With AI (EWAI) helps you plan, build and review software with an AI assistant. It gives the assistant a shared record of the project, a delivery workflow and checks against your engineering standards. You keep control of the decisions and approve implementation before it starts.
 
+## Beta: concise answers and useful decision guidance
+
+Version `0.3.1-beta.0` adds communication guidance that prioritises correctness and usefulness, then brevity. Decision requests include action details, supporting guidance, a recommendation with its reason and a suggested response when useful. Query refinement leads with a recommended interpretation and explains consequential assumptions.
+
+To try this beta in one project:
+
+```bash
+npm install --save-dev @thebackstoryis/engineering-with-ai@beta
+npx ewai
+```
+
+Initialisation or the next check-in refreshes EWAI's managed instructions in `AGENTS.md` and `CLAUDE.md`, preserving project-authored guidance outside that block. Start a fresh host conversation after the refresh. See [the user guide](Docs/context-management-and-token-efficiency.md#concise-answers-and-guided-decisions) for examples and [beta installation and recovery](Docs/operations/installation-updating-and-entitlements.md#try-the-beta-channel) for other installation choices.
+
+This beta adds communication instructions and documentation. Tool-result compaction remains planned, and incremental token or cost savings have not been measured. Mandatory workflow and human approvals still apply. The production npm channel remains on `0.3.0`.
+
 ## EWAI can now pick up the next ready piece of work
 
 If you’ve prepared several work items, you can choose which ones EWAI is allowed to take on. EWAI checks what’s ready, uses the priorities you’ve recorded to pick the next item, and starts its delivery workflow. Once you’ve separately approved the Build, it can run the approved build tasks, their tests and a fresh review.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebackstoryis/engineering-with-ai",
-  "version": "0.3.0",
+  "version": "0.3.1-beta.0",
   "description": "A human-centred, AI-augmented engineering pipeline",
   "license": "SEE LICENSE IN LICENSE",
   "author": "The Backstory Is",

package/src/project.mjs

@@ -90,6 +90,20 @@ const checkinInstructionFiles = ['AGENTS.md', 'CLAUDE.md'];
 const checkinInstruction = `<!-- EWAI-CHECKIN:START -->
 ## EWAI conversation check-in
 
+### Concise, useful output
+
+Prioritise correctness, fidelity and usefulness, then brevity. Resist verbosity: remove repetition, filler, restated requests and routine tool narration. Lead with the result or recommendation, using plain language and enough action detail to make it usable.
+
+Preserve exact commands and identifiers, prerequisites, meaningful step order, failure evidence, uncertainty and human authority. Report only verification actually performed. Follow mandatory check-in, status, consent and phase protocols. Expand when a shorter answer would hide a consequential fact or when detail is requested; do not impose arbitrary word limits.
+
+For a decision ask, include what needs deciding, relevant action details and consequences, supporting guidance, material options and tradeoffs, a recommendation with its reason, and a clear ask. Provide a suggested response when it helps the person act. If evidence is insufficient, recommend the next evidence-gathering step. Recommendations, defaults and suggested replies never constitute approval.
+
+### Query refinement
+
+Lead with the recommended interpretation or refined request, explaining consequential assumptions. Ask one focused question only when missing information materially changes the scope, outcome or next action; include supporting guidance and a recommended response with its reason. Keep uncertainty visible, preserve the user's intent and continue independent authorised work. After clarification, confirm the refined request briefly and act within its authority boundaries.
+
+### Check-in and workflow
+
 Keep the complete workflow, but present it cleanly: four routine status lines plus the returned menu at a decision point. Preserve warnings, blockers and unknown checks with short reasons; detailed diagnostics are on request. Progress is one sentence of at most 24 words per meaningful checkpoint. Do not narrate commands, file reads, JSON parsing or internal reasoning, and do not repeat the menu during a selected action. Never shorten briefing, purpose alignment, consent, standards or approval gates to meet an output limit. Use the guarded dashboard password form by default for licence setup; a private terminal prompt is an alternative only when a genuine interactive terminal is available. Never emulate hidden terminal entry through chat.
 
 When \`.ewai-pipeline/project.json\` exists, perform one EWAI check-in at the start of each new agent conversation before substantive project work. That locator identifies the configured SPECS root; do not assume it is \`./SPECS\`. Claude may receive its check-in JSON from the managed SessionStart hook; interpret that result instead of running it twice. Otherwise run \`ewai checkin --project . --json\`. This starts or reuses the project-local pipeline dashboard and refreshes its SQLite projection. Always interpret and report the EWAI version/update status, premium entitlement and installed-library status, dashboard URL, state-integrity result, mandatory standards status, configured external validators, and any configured-versus-installed CLI mismatch. Show unknown checks with their reason rather than omitting them.