diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown
index 85ec0edcefa6ad7aa74676707206348a2b0d747b..7a895cfd177b1e55631bfdac9e083adeeb559074 100644
--- a/CONTRIBUTING.markdown
+++ b/CONTRIBUTING.markdown
@@ -2,9 +2,25 @@ Contributing to The Project
 ===========================
 
 The following is a set of guidelines for contributing to this project. These
-are guidelines, not rules, so use your best judgement and feel free to propose
-changes.
+are guidelines, not rules, so use your best judgment and feel free to propose
+changes. For information about the overall design of the library and general
+coding guidelines, see the `DESIGN.markdown` file.
 
+## Contribution Workflow
+
+We basically follow the [Gitlab Flow](https://docs.gitlab.com/ee/workflow/gitlab_flow.html)
+model:
+ - `master` is the primary branch for up-to-date development
+ - any new feature/development should go into a `feature-branch` based of
+   `master` and merge into `master` after.
+ - we follow a `semi-linear history with merge commits` strategy: each merge
+   request should include clean commits, but only the HEAD and merge commit
+   need to pass CI.
+ - if the feature branch is not too complex, a single commit, even from a
+   squash is okay. If the feature branch includes too many changes, each major
+   change should appear in its own commit.
+ - to help with in-development work, CI will not activate on branches with
+   names started with wip/
 ## Commit Messages Styleguide
 
 - use present tense, imperative mood
diff --git a/DESIGN.markdown b/DESIGN.markdown
new file mode 100644
index 0000000000000000000000000000000000000000..34b30bdc67d52233e56392b8f4f950de618dde8e
--- /dev/null
+++ b/DESIGN.markdown
@@ -0,0 +1,54 @@
+Overall Design and Coding Guidelines
+====================================
+
+The AML codebase try to follow a small set of overarching principles in its
+design, as well as some more specific code style constraints.
+
+## Overal Design Principles
+
+At its core, AML is able to provide access to established, well known
+abstractions inside a common toolbox, with the more flexibility possible.
+Abstractions are made available through __building blocks__, each representing
+a single abstraction. Each building block is separated into a __generic__ API
+for operations that the abstraction provides, and __implementations__ of those
+operations for a specific implementation of the abstraction.
+
+The following principles apply when designing abstractions and implementations:
+
+1. Abstractions should be kept as minimal and as separated as possible: if two
+different functionalities seem to involve different kinds of concepts that
+could be dealt with or configured independently, they should be split into
+different building block
+
+2. Customization of a building block should happen at creation time: the goal
+is to make it easy for users to evaluate different configurations options with
+minimal impact on the inner code of the application
+
+3. Creating a new implementation of a building block is preferred to adding
+complexity to an existing implementation.
+
+4. Building blocks should interact with each other through the generic API, but
+specific implementations are allowed to break this rule for
+performance-oriented reasons. A generic version should still be available.
+
+5. Its okay for an implementation not to work unless the building block it
+depends on are from specific implementations. If possible, checks and error
+codes should be used to enforce correctness.
+
+6. Neither the opaque structures used for the generic API nor the actual
+structures used by implementations are private, as users should be able to
+customize any of those on the fly. That goes also for functions.
+
+## Coding Guidelines
+
+1. no `static` functions inside implementations, users should be able to create
+their own custom building block by combining existing code.
+
+2. no `const` pointers to functions or other objects, for the same reasons.
+
+3. no `void` return type, unless no implementation can ever fail.
+
+4. macros are UPPERCASE_WITH_UNDERSCORES, function lowercase_with_underscores
+
+5. All functions/macros should start with aml/AML followed by the name of the
+building block involved.