jason/agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fill deployment profile from workbook answers

Browse Source
This commit is contained in:
jason
2026-03-23 14:43:20 -05:00
parent 41cfbb0151
commit b65b9a8b94
2 changed files with 121 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
DEPLOYMENT-PROFILE.md
View File

@@ -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.

122
PROJECT-PROFILE-WORKBOOK.md
View File

@@ -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.