devflow-toolkit 0.3.0__py3-none-any.whl

devflow/profiles/base/constitution/constitution.md

@@ -0,0 +1,85 @@
+# Project Constitution
+
+## 1. Purpose
+
+This document defines the fundamental principles and
+development standards that all AI agents must follow
+when analyzing, planning, implementing or modifying
+this project.
+
+These principles apply to all development activities,
+including new features, bug fixes, refactoring,
+integrations and optimizations.
+
+## 2. Existing Project First
+
+- Always inspect the existing codebase before proposing
+  or implementing changes.
+- Understand the relevant modules, dependencies,
+  architecture and existing business logic.
+- Prefer extending existing components over creating
+  duplicated implementations.
+- Preserve existing behavior unless the specification
+  explicitly requires changing it.
+- Never assume that a feature must be implemented
+  from scratch.
+
+## 3. Respect Existing Architecture
+
+- Follow the established project architecture.
+- Respect module boundaries and separation of concerns.
+- Avoid introducing unnecessary dependencies.
+- Avoid duplicating business logic.
+- Do not introduce abstractions without a clear benefit.
+- Consider the impact of changes on existing components.
+
+## 4. Code Quality
+
+- Follow the standards defined in code-standards.md.
+- Follow the architectural principles defined in
+  architecture.md.
+- Apply technology-specific standards when applicable.
+
+## 5. Technology-Specific Standards
+
+When the project includes a technology-specific profile,
+follow the guidelines installed for that profile.
+
+Examples include django-standards.md for Django projects
+and fastapi-standards.md for FastAPI projects.
+
+Technology-specific guidelines must only be applied
+when the corresponding technology is present and its
+profile is enabled for the project.
+
+## 6. Change Safety
+
+- Analyze potential regressions before modifying code.
+- Preserve compatibility with existing integrations
+  unless otherwise specified.
+- Consider error handling, edge cases and data integrity.
+- Include or update automated tests when appropriate.
+- Never silently discard existing functionality.
+
+## 7. Specification Compliance
+
+- Implement only what is required by the approved
+  specification.
+- Respect the acceptance criteria.
+- Identify ambiguities instead of inventing requirements.
+- Report assumptions and relevant technical limitations.
+
+## 8. Documentation
+
+- Keep technical documentation consistent with the
+  actual implementation.
+- Update documentation when a change affects existing
+  behavior, configuration or integrations.
+
+## 9. Decision Making
+
+- Prefer simple, maintainable solutions.
+- Avoid over-engineering.
+- Explain significant architectural decisions.
+- Ask for clarification when a decision could
+  materially change the implementation.

devflow/profiles/base/profile.yaml

@@ -0,0 +1,15 @@
+name: base
+version: "1.0.0"
+description: Shared engineering standards for every DevFlow project.
+
+detection:
+  files: []
+  dependencies: []
+
+constitution:
+  - constitution.md
+  - code-standards.md
+  - architecture.md
+
+templates: []
+technologies: []

devflow/profiles/django-backend/constitution/django-standards.md

@@ -0,0 +1,64 @@
+# Django Development Standards
+
+## 1. Models
+
+- Organize models into separate files when the domain
+  or model complexity justifies it.
+- Use Meta classes to define ordering, indexes
+  and database constraints.
+- Place model-related business logic in models
+  when appropriate.
+- Avoid placing unrelated business logic in models.
+- Use database constraints to enforce important
+  data integrity rules.
+
+## 2. Views and API Endpoints
+
+- Keep views thin and focused on HTTP responsibilities.
+- Delegate complex business logic to services.
+- Use class-based views for standard CRUD operations
+  when appropriate.
+- Use function-based views for simple actions
+  when they provide better clarity.
+- Validate incoming data using serializers
+  or appropriate validation components.
+- Keep response handling consistent with the
+  existing API conventions.
+
+## 3. Services
+
+- Place complex business logic in a services/ package.
+- Organize services around domain concepts.
+- Keep services focused and cohesive.
+- Prefer stateless services when possible.
+- Avoid unnecessary service layers for simple operations.
+
+## 4. Query Optimization
+
+- Use select_related() for ForeignKey and OneToOneField
+  relationships.
+- Use prefetch_related() for ManyToManyField
+  and reverse relationships.
+- Use only() or defer() when partial field retrieval
+  provides a measurable benefit.
+- Use exists() for boolean existence checks.
+- Avoid N+1 queries.
+- Inspect generated queries when performance
+  is a concern.
+
+## 5. Transactions and Data Integrity
+
+- Use transaction.atomic() when multiple database
+  operations must succeed or fail together.
+- Handle integrity errors appropriately.
+- Avoid unnecessary long-running transactions.
+- Respect existing tenant and database isolation
+  mechanisms.
+
+## 6. Testing
+
+- Follow the project's existing testing conventions.
+- Test successful operations and relevant failure cases.
+- Cover permissions, validation and edge cases.
+- Reuse existing factories, fixtures and test utilities.
+- Avoid duplicating test setup unnecessarily.

devflow/profiles/django-backend/profile.yaml

@@ -0,0 +1,24 @@
+name: django-backend
+version: "1.0.0"
+description: Django backend development profile.
+
+detection:
+  files:
+    - manage.py
+  dependencies:
+    - django
+    - djangorestframework
+  indicators:
+    - manage.py
+    - settings.py
+    - urls.py
+
+constitution:
+  - django-standards.md
+
+templates: []
+
+technologies:
+  - python
+  - django
+  - django-rest-framework

devflow/profiles/fastapi-backend/constitution/fastapi-standards.md

@@ -0,0 +1,59 @@
+# FastAPI Development Standards
+
+## 1. Application Structure
+
+- Keep application bootstrap and configuration in a
+  dedicated module.
+- Group routes by domain using routers.
+- Keep request handling, business logic and data access
+  separated.
+- Reuse existing dependency injection patterns before
+  introducing new ones.
+
+## 2. Routes and Schemas
+
+- Keep route handlers focused on HTTP concerns.
+- Declare explicit request and response models.
+- Define response models and status codes explicitly.
+- Keep error responses consistent with the existing API.
+- Avoid exposing internal ORM models through the API.
+
+## 3. Async and I/O
+
+- Do not block the event loop with synchronous I/O.
+- Use async database and HTTP clients consistently.
+- Set timeouts on external calls.
+- Propagate cancellation where appropriate.
+- Avoid unnecessary concurrency and background tasks.
+
+## 4. Dependencies and Services
+
+- Use FastAPI dependencies for shared request concerns.
+- Place business logic in services rather than routes.
+- Keep services focused and testable.
+- Reuse existing sessions, clients and configuration.
+- Avoid hidden global state.
+
+## 5. Data Access
+
+- Scope database sessions to the request or unit of work.
+- Avoid N+1 queries and unnecessary eager loading.
+- Use transactions for operations that must be atomic.
+- Retrieve only the data required by the endpoint.
+- Handle integrity and not-found errors explicitly.
+
+## 6. Validation and Security
+
+- Validate input with typed schemas.
+- Enforce authentication and authorization at the
+  appropriate layer.
+- Do not trust client-provided identifiers or roles.
+- Avoid leaking secrets or internal details in errors.
+- Consider rate limits and payload size limits when relevant.
+
+## 7. Testing
+
+- Follow the existing test layout and fixtures.
+- Test success, validation, permission and failure paths.
+- Use dependency overrides rather than global mocks.
+- Keep tests independent and deterministic.

devflow/profiles/fastapi-backend/profile.yaml

@@ -0,0 +1,23 @@
+name: fastapi-backend
+version: "1.0.0"
+description: FastAPI backend development profile.
+
+detection:
+  files: []
+  dependencies:
+    - fastapi
+    - uvicorn
+  indicators:
+    - main.py
+    - routers
+    - dependencies
+
+constitution:
+  - fastapi-standards.md
+
+templates: []
+
+technologies:
+  - python
+  - fastapi
+  - async

devflow/prompts/__init__.py

@@ -0,0 +1,200 @@
+"""Loading and rendering of shared harness-independent prompts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from devflow.core.config import AgentPermissions
+
+PROMPTS_ROOT = Path(__file__).resolve().parent
+
+
+class PromptError(Exception):
+  """Raised when a bundled prompt cannot be loaded."""
+
+
+def load_prompt(name: str) -> str:
+  """Load a bundled prompt template by filename."""
+  path = PROMPTS_ROOT / name
+  try:
+    return path.read_text(encoding="utf-8")
+  except OSError as error:
+    msg = f"Could not read prompt template: {path}"
+    raise PromptError(msg) from error
+
+
+def build_spec_prompt(
+  *,
+  request: str,
+  project_name: str,
+  context_path: str,
+  spec_path: str,
+  constitution_paths: list[str],
+  harness_name: str,
+  execution_mode: str,
+  permissions: AgentPermissions,
+  project_mode: str = "existing",
+  architecture_path: str = "",
+  architecture_digest: str = "",
+  architecture_style: str = "",
+  discovery_path: str = "",
+  discovery_digest: str = "",
+  discovery_decisions: list[str] | None = None,
+) -> str:
+  """Render the shared specification prompt for any harness."""
+  template_name = (
+    "spec.greenfield.md"
+    if project_mode == "greenfield"
+    else "spec.md"
+  )
+  template = load_prompt(template_name)
+  mode_instructions = _mode_instructions(
+    execution_mode,
+    spec_path,
+    permissions,
+  )
+  architecture_note = ""
+  if architecture_path:
+    architecture_note = (
+      f"- Declared architecture manifest: `{architecture_path}`\n"
+      f"- Architecture digest: `{architecture_digest}`\n"
+      f"- Declared architecture style: {architecture_style}\n"
+    )
+  discovery_note = ""
+  if discovery_path:
+    discovery_note = (
+      f"- Discovery record: `{discovery_path}`\n"
+      f"- Discovery digest: `{discovery_digest}`\n"
+    )
+    for decision in discovery_decisions or []:
+      discovery_note += f"- Discovery decision: {decision}\n"
+  replacements = {
+    "request": request,
+    "project_name": project_name,
+    "context_path": context_path,
+    "spec_path": spec_path,
+    "constitution_paths": (
+      ", ".join(f"`{path}`" for path in constitution_paths)
+      or "none"
+    ),
+    "harness_name": harness_name,
+    "execution_mode": execution_mode,
+    "project_mode": project_mode,
+    "architecture_note": architecture_note,
+    "discovery_note": discovery_note,
+    "mode_instructions": mode_instructions,
+    "permission_summary": _permission_summary(permissions),
+  }
+  rendered = template
+  for key, value in replacements.items():
+    rendered = rendered.replace("{{" + key + "}}", value)
+  return rendered
+
+
+def build_discovery_prompt(
+  *,
+  request: str,
+  project_name: str,
+  context_path: str,
+  discovery_path: str,
+  harness_name: str,
+  execution_mode: str,
+  permissions: AgentPermissions,
+) -> str:
+  """Render the interactive discovery prompt for any harness."""
+  template = load_prompt("discovery.md")
+  replacements = {
+    "request": request,
+    "project_name": project_name,
+    "context_path": context_path,
+    "discovery_path": discovery_path,
+    "harness_name": harness_name,
+    "execution_mode": execution_mode,
+    "mode_instructions": _discovery_mode_instructions(
+      discovery_path,
+      execution_mode,
+      permissions,
+    ),
+    "permission_summary": _permission_summary(permissions),
+  }
+  rendered = template
+  for key, value in replacements.items():
+    rendered = rendered.replace("{{" + key + "}}", value)
+  return rendered
+
+
+def _discovery_mode_instructions(
+  discovery_path: str,
+  execution_mode: str,
+  permissions: AgentPermissions,
+) -> str:
+  if execution_mode != "interactive":
+    return (
+      "Discovery is incomplete. Do not write a specification and do "
+      "not invent answers. Report the pending questions and stop."
+    )
+  if not permissions.allow_spec_write:
+    return (
+      "Discovery is incomplete, but artifact writes are disabled. Ask "
+      "the user for explicit answers and acceptance, then report them "
+      "verbatim. Do not write the specification."
+    )
+  return (
+    "You are running interactively. Read the discovery record and ask "
+    "the user only about pending blocking questions and proposed "
+    "assumptions. Record only explicit answers. Update the same "
+    f"`{discovery_path}` file in place, preserving every existing id, "
+    "category, blocking flag and question text. Set an answered "
+    "question to `status: answered` with `answer`, `answered_by: user` "
+    "and an ISO-8601 `answered_at` timestamp. Set an accepted "
+    "assumption to `status: accepted` with `accepted_by: user` and "
+    "`accepted_at`. Never accept an assumption on the user's behalf. "
+    "Never change the request, project_mode, spec_id or change. Do not "
+    "write or modify `spec.md` in this phase. When no pending blocking "
+    "question or unaccepted assumption remains, stop and report that "
+    "Discovery is complete."
+  )
+
+
+def _mode_instructions(
+  execution_mode: str,
+  spec_path: str,
+  permissions: AgentPermissions,
+) -> str:
+  if execution_mode == "interactive":
+    if permissions.allow_spec_write:
+      return (
+        "You are running interactively. Ask concise clarifying questions "
+        "whenever missing information would change requirements or "
+        "acceptance criteria. Resolve what you can with the user, then "
+        f"write the complete specification to `{spec_path}` using the "
+        "available file tools. Do not finish until that file exists and "
+        "contains the complete document."
+      )
+    return (
+      "You are running interactively, but specification writes are "
+      "disabled. Ask clarifying questions and return the complete "
+      "specification as your final message. DevFlow will record the "
+      "deterministic fallback specification."
+    )
+
+  return (
+    "You are running non-interactively. Do not ask the user questions "
+    "and do not write files. Put every unresolved question or assumption "
+    "in section 7. Return only the complete Markdown specification as "
+    "your final answer. DevFlow will validate it and write it to "
+    f"`{spec_path}`."
+  )
+
+
+def _permission_summary(permissions: AgentPermissions) -> str:
+  def status(value: bool) -> str:
+    return "allowed" if value else "denied"
+
+  return (
+    f"- Project read: {status(permissions.allow_project_read)}\n"
+    f"- Specification write: {status(permissions.allow_spec_write)}\n"
+    "- Source code changes: "
+    f"{status(permissions.allow_source_code_changes)}\n"
+    "- Source changes remain out of scope for specification generation."
+  )

devflow/prompts/discovery.md

@@ -0,0 +1,119 @@
+# DevFlow Discovery Task
+
+You are the discovery agent for the project `{{project_name}}`.
+
+## Source of Truth
+
+- Change request: {{request}}
+- Static analysis context: `{{context_path}}`
+- Discovery record: `{{discovery_path}}`
+- Harness: {{harness_name}}
+- Execution mode: {{execution_mode}}
+
+Read the context and the discovery record before talking to the user.
+The discovery record is the only place where answers and assumption
+acceptance may be recorded.
+
+## Purpose
+
+Discovery decides whether the request is ready to become a
+specification. It does not write the specification and it does not
+change application code.
+
+A specification may only be generated when:
+
+- every question with `blocking: true` has an explicit answer; and
+- every proposed assumption has been explicitly accepted.
+
+Questions with `blocking: false` may remain pending. Never change a
+question from blocking to non-blocking without a clear justification
+based on user-visible behavior, data, security, integrations,
+dependencies, deployment or architecture boundaries.
+
+## Non-Negotiable Boundaries
+
+- Do not write, overwrite or delete `spec.md`.
+- Do not modify application source code, tests, configuration,
+  dependencies or the constitution.
+- Do not invent answers. If the user is unsure, leave the question
+  pending and explain what decision is needed.
+- Do not accept assumptions on the user's behalf. Acceptance is an
+  explicit human action.
+- Preserve every existing id, question text, category, blocking flag,
+  option, request, `spec_id`, `change` and `project_mode`.
+- Record only what the user explicitly said. Do not summarize away
+  details that change scope.
+
+## Discovery Record Format
+
+The file is YAML with this shape:
+
+```yaml
+version: 1
+spec_id: "001"
+change: "001-short-slug"
+request: "Original request"
+project_mode: existing
+status: awaiting_clarification
+created_at: "YYYY-MM-DDTHH:MM:SSZ"
+updated_at: "YYYY-MM-DDTHH:MM:SSZ"
+questions:
+  - id: Q1
+    category: functional_scope
+    question: "..."
+    reason: "..."
+    blocking: true
+    status: answered
+    options: []
+    answer: "..."
+    answered_by: user
+    answered_at: "YYYY-MM-DDTHH:MM:SSZ"
+assumptions:
+  - id: A1
+    question_id: Q1
+    value: "..."
+    reason: "..."
+    source: agent_default
+    status: accepted
+    accepted_by: user
+    accepted_at: "YYYY-MM-DDTHH:MM:SSZ"
+```
+
+Valid question categories are `functional_scope`, `user_behavior`,
+`data_persistence`, `security_authentication`,
+`external_integration`, `architecture_boundary`, `dependencies` and
+`deployment`.
+
+Valid question statuses are `pending` and `answered`. Valid assumption
+statuses are `pending_acceptance` and `accepted`.
+
+An answered question requires `answer`, `answered_by` and
+`answered_at`. An accepted assumption requires `accepted_by` and
+`accepted_at`. A pending item must not contain those fields.
+
+Update `updated_at` whenever the file changes. Set `status` to
+`awaiting_clarification` while anything blocking or unaccepted
+remains, and to `complete` only when nothing does.
+
+## Conversation Rules
+
+- Ask one focused question at a time.
+- Explain why the answer changes the specification.
+- Offer the recorded options when they exist, but accept a free-form
+  answer when it is clearer.
+- For each proposed assumption, state the proposal and ask for
+  explicit acceptance or rejection. If rejected, ask what to do
+  instead.
+- Stop asking once every blocking decision is resolved. Do not pad the
+  conversation with optional preferences.
+
+## Execution Instructions
+
+{{mode_instructions}}
+
+## Permission Summary
+
+{{permission_summary}}
+
+Return a short report of what was answered, what was accepted and what
+remains pending. Do not generate the specification.