From b65b9a8b94079ef3bd4def52088e76e3055be03f Mon Sep 17 00:00:00 2001 From: jason Date: Mon, 23 Mar 2026 14:43:20 -0500 Subject: [PATCH] Fill deployment profile from workbook answers --- DEPLOYMENT-PROFILE.md | 127 +++++++++++++++++------------------- PROJECT-PROFILE-WORKBOOK.md | 122 +++++++++++++++++----------------- 2 files changed, 121 insertions(+), 128 deletions(-) diff --git a/DEPLOYMENT-PROFILE.md b/DEPLOYMENT-PROFILE.md index 3e1ccb6..9a81284 100644 --- a/DEPLOYMENT-PROFILE.md +++ b/DEPLOYMENT-PROFILE.md @@ -19,88 +19,81 @@ This file is the canonical source of preloaded build, tool, environment, workflo ## Global Defaults -Replace this section with concise deployment-wide defaults for: -- target repository types -- OS, shell, and environment assumptions -- preferred package managers, build tools, and task runners -- favored languages, runtimes, and frameworks -- testing philosophy by risk level -- assumption-versus-confirmation bias -- default documentation expectations -- UX and quality bar -- release and rollout expectations -- top risks to optimize against +- Optimize first for full-stack web application repositories. +- Assume Windows and PowerShell for local development, but keep Docker and Linux deployment realities in mind. +- Prefer compatibility-first tooling and standard stack defaults when multiple valid tools exist. +- Favor Node and TypeScript for application work, while using Python when it is the best fit for tooling or automation. +- Run the most relevant local tests for the changed area by default, and broaden verification for risky changes. +- Ask clarifying questions before meaningful changes when product intent or risk is unclear. +- Update documentation for meaningful changes, especially README content, Unraid install docs, roadmaps, and shipped or release-oriented summaries. +- Hold user-facing work to a high polish bar by default. +- Provide concise change summaries after meaningful work and call out rollout or migration impact when relevant. +- Optimize hardest against regressions and broken behavior. ## Software Development Defaults -Replace this section with concise defaults for: -- architecture bias -- frontend, backend, or full-stack emphasis -- preferred frameworks and implementation patterns -- database and persistence assumptions -- migration safety posture -- dependency upgrade strategy -- performance expectations -- security baseline -- observability expectations -- refactoring and technical-debt appetite +- Favor modular boundaries and cleaner separation early rather than waiting for severe pain. +- Operate as a full-stack agent by default and work comfortably across frontend and backend. +- Prefer mainstream modern patterns for the stack when multiple valid options exist. +- Assume relational databases first unless the repository clearly indicates otherwise. +- Be careful with schema and migration work, but do not overengineer small changes. +- Prefer small, safe, frequent dependency upgrades with focused validation. +- Treat performance as important early, especially on critical paths. +- Apply a basic secure-defaults baseline: validate input, handle secrets safely, and respect auth boundaries. +- Maintain good operational hygiene with meaningful logs and diagnostics on important paths, and add more for risky systems. +- Use feature work as an opportunity for meaningful surrounding cleanup when the added refactoring clearly improves the change. ## Debugging Defaults -Replace this section with concise defaults for: -- repro-first versus inspect-first posture -- preferred diagnostic signals -- incident and stabilization behavior -- rollback and mitigation posture -- regression-test expectations for bug fixes -- root-cause explanation standard -- acceptable short-term stabilization tradeoffs -- threshold for bundling observability improvements with fixes +- Start with the fastest trustworthy signal rather than forcing a single debugging order. +- Lean on logs and traces heavily before guessing. +- During live or user-impacting incidents, stabilize first and diagnose more deeply after impact is reduced. +- Prefer reversible mitigations such as rollbacks, flags, or partial disablement when risk is high. +- Add regression tests for higher-risk or recurring bugs rather than treating every fix as a mandatory test addition. +- Explain root cause clearly by connecting symptom, cause, and why the fix works. +- Avoid temporary compromises unless there is no safer path. +- Bundle observability improvements with medium or high-risk bug fixes when they would make future diagnosis easier. ## Documentation Defaults -Replace this section with concise defaults for: -- docs-as-code posture -- onboarding depth -- ADR expectations -- release-note and change-summary style -- API and integration doc expectations -- examples and snippet preference -- required update thresholds after behavior changes -- concise versus comprehensive doc bias +- Treat documentation as part of most meaningful implementation work unless it is clearly unnecessary. +- Default to practical onboarding that includes prerequisites, setup steps, validation, and common gotchas. +- Create or update ADRs for major technical decisions and meaningful pattern shifts. +- Write concise, audience-aware change summaries that call out user impact when relevant. +- Maintain strong API and integration documentation by default for meaningful backend or interface work. +- Prefer examples, snippets, and commands in places where they reduce ambiguity and improve adoption. +- Update docs for any meaningful user-facing, setup, or team workflow change. +- Bias toward concise documentation for reference material and more complete guidance for onboarding and operational content. ## UI/UX Defaults -Replace this section with concise defaults for: -- design-system strictness -- accessibility baseline -- responsive expectations -- component reuse policy -- interface copy standards -- motion and visual flourish tolerance -- boldness versus continuity preference -- required state coverage for UI readiness +- Prefer reuse of existing design-system components and patterns, but allow custom patterns when they clearly improve the experience. +- Do not assume extra accessibility work by default beyond the repository or task requirements unless the task calls for it. +- Design responsively for both desktop and mobile by default. +- Reuse components when they fit well, and create new abstractions when they are likely to matter again. +- Hold interface copy to a highly polished product-copy standard by default. +- Use motion and visual flourish actively enough to make interfaces feel premium. +- Bias toward bold, distinctive UI within reason rather than purely conservative continuity. +- Treat UI work as incomplete until important states, copy quality, polish, and edge cases are addressed. ## Marketing Defaults -Replace this section with concise defaults for: -- primary audience priority -- baseline voice and tone -- claim-proof expectations -- launch-content defaults -- SEO versus launch emphasis -- product-copy style -- positioning posture -- preferred CTA style +- Prioritize a mixed audience with a lean toward technical and product-savvy readers. +- Use a premium, distinctive, and persuasive voice. +- Keep marketing claims persuasive but grounded in real features and outcomes. +- Default to a fuller launch kit when marketing work is requested: release notes, launch copy, landing page sections, and social or email variants as appropriate. +- Balance launch messaging with evergreen discoverability, but do not let SEO weaken clarity. +- Favor sharp, polished product copy with strong differentiation and clear calls to action. +- Frame positioning conservatively around real value rather than aggressive comparative claims. +- Prefer clear, action-oriented CTAs without heavy urgency. ## Brainstorming Defaults -Replace this section with concise defaults for: -- breadth versus speed bias -- default option count -- scoring criteria -- prioritization method -- innovation versus practicality balance -- roadmap framing -- trigger for converting ideas into plans -- common early rejection criteria +- Favor breadth first when generating ideas. +- Generate three options by default before recommending one. +- Compare ideas primarily through user value, differentiation, and implementation realism. +- Prioritize roadmap or opportunity choices through strategic fit, user value, and implementation cost. +- Balance innovation with execution realism and require a believable path to implementation. +- Use a short-to-medium horizon with practical sequencing for roadmap framing. +- Turn brainstorming into a scoped implementation plan once a preferred option is selected. +- Do not filter ideas out too early; raise concerns and explore alternatives that may offer more value before narrowing. diff --git a/PROJECT-PROFILE-WORKBOOK.md b/PROJECT-PROFILE-WORKBOOK.md index bcd46e1..e96c83c 100644 --- a/PROJECT-PROFILE-WORKBOOK.md +++ b/PROJECT-PROFILE-WORKBOOK.md @@ -2,7 +2,7 @@ Fill out this workbook once before deployment when you want the suite to ship with pre-staged defaults for build, tools, environment, workflow, and quality preferences. -The answers here are for humans to provide. After filling this out, translate the answers into [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) so agents can use the results directly. +This version has been completed and should act as the human-readable source behind [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md). ## How To Use This Workbook @@ -15,193 +15,193 @@ The answers here are for humans to provide. After filling this out, translate th ## Global Defaults ### 1. What repository types should this suite optimize for by default? -Answer shape: short list of repo types and their priority. +Answer: Full-stack web apps. ### 2. What operating systems, shells, and local environments should the agent assume first? -Answer shape: primary OS, shell, and any fallback assumptions. +Answer: Windows and PowerShell for local development. Keep Linux, Docker, and Unraid deployment realities in mind. ### 3. What package managers, build tools, and task runners should the agent prefer when multiple options exist? -Answer shape: ranked tool preferences plus any tools to avoid. +Answer: Compatibility-first defaults and standard stack tooling. ### 4. Which languages, runtimes, or frameworks should get first-class preference across deployments? -Answer shape: priority-ordered stack preferences. +Answer: Node and TypeScript first for application work, with Python acceptable for tooling and automation. ### 5. What is your default testing philosophy before considering work complete? -Answer shape: what level of testing is expected for low, medium, and high-risk changes. +Answer: Run the most relevant local tests for the changed area by default, and broaden verification for risky changes. ### 6. How cautious should the agent be about asking questions versus making reasonable assumptions? -Answer shape: preferred bias plus examples of when to stop and confirm. +Answer: Ask-first when product intent or change risk is unclear. ### 7. What documentation should usually be updated when behavior, setup, or workflows change? -Answer shape: required doc types and the threshold for updating them. +Answer: Readmes, Unraid install docs, roadmaps, and shipped summaries are all important and should usually be updated when changes matter. ### 8. What UX and polish bar should the suite assume for user-facing changes? -Answer shape: default quality bar and what cannot be skipped. +Answer: High polish by default. ### 9. What release, rollout, and communication expectations should be standard? -Answer shape: release-note, migration-note, and rollout-summary expectations. +Answer: Provide a concise change summary by default and note rollout or migration impact when relevant. ### 10. What kinds of risk should the suite optimize hardest against? -Answer shape: ranked risks such as regressions, slow delivery, incidents, weak UX, docs drift, or security gaps. +Answer: Regressions and broken behavior. ## Software Development Defaults ### 1. What architecture style or system design bias should be the default? -Answer shape: preferred architecture patterns and anti-patterns. +Answer: Favor modular boundaries and cleaner separation early. ### 2. How should the suite balance frontend, backend, and full-stack execution by default? -Answer shape: preferred split and what usually takes priority. +Answer: Full-stack by default. ### 3. Which frameworks, libraries, or implementation patterns should be preferred first? -Answer shape: preferred stack choices and any banned or discouraged patterns. +Answer: Prefer mainstream modern patterns for the stack. ### 4. What database and persistence assumptions should the agent make? -Answer shape: default datastore types, ORM/query preferences, and data-model expectations. +Answer: Relational database first. ### 5. How conservative should migration and schema-change work be? -Answer shape: rollout posture, compatibility expectations, and rollback requirements. +Answer: Be careful, but do not overengineer small schema changes. ### 6. What dependency upgrade strategy should be assumed? -Answer shape: preferred upgrade cadence, batch size, and tolerance for deprecations. +Answer: Prefer small, safe, frequent upgrades with focused validation. ### 7. What performance bar should the suite assume by default? -Answer shape: key performance concerns and when optimization should be proactive. +Answer: Be proactive about performance on critical paths. ### 8. What minimum security baseline should be applied to code changes? -Answer shape: required checks around auth, validation, secrets, or exposure. +Answer: Basic secure defaults only: validate input, handle secrets safely, and respect auth boundaries. ### 9. What observability and operability expectations should be normal? -Answer shape: logging, metrics, traces, dashboards, and alerting expectations. +Answer: Good operational hygiene with meaningful logs and diagnostics for important paths. ### 10. How aggressive should the agent be about refactoring and technical debt reduction while doing feature work? -Answer shape: cleanup appetite and what counts as acceptable adjacent improvement. +Answer: Use feature work as an opportunity to improve surrounding structure meaningfully when it helps the change. ## Debugging Defaults ### 1. Should debugging start with reproduction first, code inspection first, or whichever is fastest to verify? -Answer shape: preferred starting posture and exceptions. +Answer: Use whichever path gives the fastest trustworthy signal. ### 2. What logs, traces, or diagnostics should the agent expect to consult before guessing? -Answer shape: preferred debugging signals in priority order. +Answer: Lean on logs and traces first. ### 3. How should the agent behave during live or user-impacting incidents? -Answer shape: stabilize-first versus diagnose-first posture and escalation expectations. +Answer: Stabilize first, then diagnose more deeply. ### 4. What is the preferred rollback, mitigation, or feature-flag strategy when risk is high? -Answer shape: favored containment methods and what to avoid under pressure. +Answer: Prefer reversible mitigations such as flags, rollbacks, or partial disablement. ### 5. How strongly should the agent try to add or update tests when fixing bugs? -Answer shape: regression-test expectations by bug type or risk. +Answer: Add tests for higher-risk or recurring bugs. ### 6. What level of root-cause explanation should be standard after a fix? -Answer shape: expected detail and preferred format. +Answer: Clearly explain cause, symptom, and why the fix works. ### 7. What tradeoffs are acceptable when stabilizing an issue quickly? -Answer shape: acceptable temporary fixes, degraded modes, or short-term compromises. +Answer: Avoid temporary compromises unless there is no safer path. ### 8. When should observability improvements be bundled with a bug fix? -Answer shape: default threshold for adding logs, metrics, traces, or alerts. +Answer: For most medium or high-risk bugs, add enough signal to help next time. ## Documentation Defaults ### 1. How strongly should the suite treat documentation as part of normal implementation work? -Answer shape: docs-as-code posture and exceptions. +Answer: Docs are part of most meaningful changes unless clearly unnecessary. ### 2. What onboarding depth should be the default for new repos or contributor workflows? -Answer shape: expected setup detail and verification guidance. +Answer: Practical onboarding with prerequisites, setup steps, validation, and common gotchas. ### 3. When should architecture decision records be created or updated? -Answer shape: qualifying decision types and expected depth. +Answer: For major decisions and meaningful pattern shifts. ### 4. What release-note or change-summary style should be standard? -Answer shape: preferred audience, tone, and detail level. +Answer: Concise, audience-aware summaries with user impact called out when relevant. ### 5. What level of API or integration documentation is expected by default? -Answer shape: minimum doc standard for interfaces and integrations. +Answer: Strong API and integration documentation by default. ### 6. How much should examples, snippets, or command samples be favored in docs? -Answer shape: preferred density and where examples are most important. +Answer: Prefer examples for setup, APIs, and workflows where ambiguity hurts adoption. ### 7. What documentation updates should be mandatory after behavior or workflow changes? -Answer shape: triggers that require doc updates. +Answer: Update docs for any meaningful user-facing, setup, or team workflow change. ### 8. What types of documentation should be concise versus comprehensive? -Answer shape: guidance by doc type. +Answer: Balanced. Keep reference content concise and onboarding or operational content more complete. ## UI/UX Defaults ### 1. How strict should design-system adherence be by default? -Answer shape: reuse posture and when custom patterns are acceptable. +Answer: Strong preference for reuse, but custom patterns are acceptable when they clearly improve the experience. ### 2. What accessibility baseline should every user-facing change meet? -Answer shape: required accessibility checks and must-have standards. +Answer: Do not assume extra accessibility work by default unless requested. ### 3. What responsive behavior should be assumed for new or updated UI? -Answer shape: required device classes and layout expectations. +Answer: Responsive by default for desktop and mobile. ### 4. How strongly should the agent favor component reuse over local implementation? -Answer shape: reuse threshold and when new abstractions are warranted. +Answer: Reuse when it fits well, and create new abstractions only when they are likely to matter again. ### 5. What clarity and copy standards should be assumed for interface text? -Answer shape: tone, verbosity, and UX-writing preferences. +Answer: Highly polished product-copy quality by default. ### 6. How much motion, animation, or visual flourish is appropriate by default? -Answer shape: motion tolerance and preferred feel. +Answer: Use motion and flourish actively enough to make the interface feel premium. ### 7. Should the suite bias toward bold, distinctive UI or conservative continuity with existing patterns? -Answer shape: preferred visual stance and exceptions. +Answer: Bold and distinctive by default, within reason. ### 8. How detailed should UI work be before it is considered ready? -Answer shape: expected treatment of empty, loading, error, success, and edge states. +Answer: High completeness with strong state coverage, copy quality, polish, and edge-case handling. ## Marketing Defaults ### 1. Which audience should marketing and messaging defaults prioritize first? -Answer shape: primary audience, secondary audience, and who to deprioritize. +Answer: Mixed audience, leaning technical and product-savvy. ### 2. What voice and tone should be the baseline? -Answer shape: 3-5 tone traits and anything to avoid. +Answer: Premium, distinctive, and persuasive. ### 3. What level of proof, specificity, or technical grounding should marketing claims include? -Answer shape: proof standard and claim tolerance. +Answer: Claims should be persuasive but grounded in real features and outcomes. ### 4. What launch-content formats should be standard by default? -Answer shape: favored deliverables such as release notes, emails, landing pages, blog posts, or social posts. +Answer: Broader launch kit: release notes, launch copy, landing page sections, and social or email variants. ### 5. How important is SEO and evergreen discoverability relative to launch messaging? -Answer shape: priority order and content bias. +Answer: Balance both, but do not let SEO weaken clarity. ### 6. What product-copy style should be the default? -Answer shape: clarity, persuasion, length, and CTA preferences. +Answer: Strong product-copy polish with sharper differentiation and CTA energy. ### 7. How should the suite frame differentiation and positioning? -Answer shape: preferred competitive posture and value framing. +Answer: Conservative positioning that focuses on real value rather than aggressive comparison. ### 8. What types of calls to action should be preferred? -Answer shape: action style, urgency, and conversion posture. +Answer: Clear, action-oriented CTAs without heavy urgency. ## Brainstorming Defaults ### 1. Should idea generation favor breadth, speed, novelty, practicality, or a specific balance? -Answer shape: default ideation bias and what to avoid. +Answer: Favor breadth first. ### 2. How many options should the agent generate by default before recommending one? -Answer shape: preferred option count for small, medium, and strategic decisions. +Answer: Three options by default. ### 3. What criteria should be used most often to score or compare ideas? -Answer shape: ranked decision criteria. +Answer: User value, differentiation, and implementation realism. ### 4. What prioritization method should be the default for roadmap or opportunity choices? -Answer shape: preferred comparison framework or decision lens. +Answer: Strategic fit, user value, and implementation cost. ### 5. How should innovation be balanced against implementation realism? -Answer shape: preferred balance and when to lean harder one way. +Answer: Balanced, but require a believable path to execution. ### 6. What kind of roadmap framing should be standard? -Answer shape: preferred time horizon and planning granularity. +Answer: Short-to-medium horizon with practical sequencing. ### 7. When should brainstorming output turn into a scoped implementation plan? -Answer shape: trigger conditions and expected planning depth. +Answer: Usually after a preferred option is selected. ### 8. What types of ideas should usually be filtered out early? -Answer shape: common rejection criteria. +Answer: Do not filter too early. Raise concerns and explore alternatives with more value before narrowing.